API Reference

Substructure

Classes

AuthorizationCodeSession(client_id, …[, …])

Session for authorization code flow

ClientCredentialsSession(client_id, …[, …])

Credentials(client_id, client_secret, …)

Method generated by attrs for class Credentials.

ImplicitGrantSession(client_id, redirect_uri)

Session following the “implicit grant flow” for authorization

Spotify(session)

Simple spotify web API client.

class spotipie.Spotify(session)[source]

Bases: object

Simple spotify web API client. It returns dictionaries matching exactly what is returned by the API as JSON. It implements all endpoints, including the beta endpoints.

Parameters

session (BaseOAuth2Session) –

API_BASE_URL = 'https://api.spotify.com/v1'
TYPE_TO_METHOD_NAME = {'album': 'album', 'artist': 'artist', 'playlist': 'playlist', 'track': 'track', 'user': 'user_public_profile'}
get(uri_or_url, **kwargs)[source]

Returns an object (track, album, artist, playlist or user) given its spotify URI or URL.

for ... in iter(start_page)[source]

Returns an iterator of all the items in a sequence of pages (dictionary with ‘items’ and ‘next’ keys). For example:

all_playlist_tracks = list(client.all(playlist['tracks']))
all_album_tracks = list(client.all(album['tracks']))
next_page(page)[source]

Returns the next result given a paged result

Parameters

page – a previously returned paged result

previous_page(result)[source]

Returns the previous result given a paged result

Parameters

result – a previously returned paged result

album(album_id, market=None)[source]

Get Spotify catalog information for a single album. https://developer.spotify.com/documentation/web-api/reference/albums/get-album/

album_tracks(album_id, limit=20, offset=0, market=None)[source]

Get Spotify catalog information about an album’s tracks. https://developer.spotify.com/documentation/web-api/reference/albums/get-albums-tracks/

Parameters
  • album_id

  • limitOptional. The maximum number of tracks to return. Default: 20. Minimum: 1. Maximum: 50.

  • offsetOptional. The index of the first track to return. Default: 0 (the first object). Use with limit to get the next set of tracks.

  • marketOptional. An ISO 3166-1 alpha-2 country code

albums(ids, market=None)[source]

Get Spotify catalog information for multiple albums identified by their Spotify IDs. https://developer.spotify.com/documentation/web-api/reference/albums/get-several-albums/

Parameters
  • idsRequired. A list of the Spotify IDs. Maximum: 20 IDs.

  • marketOptional. An ISO 3166-1 alpha-2 country code

artist(artist_id)[source]

Get Spotify catalog information for a single artist identified by their unique Spotify ID. https://developer.spotify.com/documentation/web-api/reference/artists/get-artist/

artist_albums(artist_id, include_groups=None, market=None, limit=20, offset=0)[source]

Get Spotify catalog information about an artist’s albums. Optional parameters can be specified in the query string to filter and sort the response_args. https://developer.spotify.com/documentation/web-api/reference/artists/get-artists-albums/

Parameters
  • artist_id

  • include_groupsOptional. A comma-separated list of keywords that will be used to filter the response_args. If not supplied, all album types will be returned. Valid values are: - album - single - appears_on - compilation For example: include_groups=album,single.

  • marketOptional. An ISO 3166-1 alpha-2 country code or the string from_token. Supply this parameter to limit the response_args to one particular geographical market. For example, for albums available in Sweden: market=SE. If not given, results will be returned for all markets and you are likely to get duplicate results per album, one for each market in which the album is available!

  • limitOptional. The number of album objects to return. Default: 20. Minimum: 1. Maximum: 50.

  • offsetOptional. The index of the first album to return. Default: 0 (i.e., the first album). Use with limit to get the next set of albums.

artist_top_tracks(artist_id, market)[source]

Get Spotify catalog information about an artist’s top tracks by country. https://developer.spotify.com/documentation/web-api/reference/artists/get-artists-top-tracks/

Parameters

Get Spotify catalog information about artists similar to a given artist. Similarity is based on analysis of the Spotify community’s listening history. https://developer.spotify.com/documentation/web-api/reference/artists/get-related-artists/

Parameters

artist_id – The Spotify ID for the artist.

artists(ids)[source]

Get Spotify catalog information for several artists based on their Spotify IDs. https://developer.spotify.com/documentation/web-api/reference/artists/get-several-artists/

Parameters

ids – A list of the Spotify IDs. Maximum: 50 IDs.

category(category_id, country=None, locale=None)[source]

Get a single category used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab). https://developer.spotify.com/documentation/web-api/reference/browse/get-category/

Parameters
  • category_id – The Spotify category ID for the category.

  • countryOptional. A country: an ISO 3166-1 alpha-2 country code. Provide this parameter to ensure that the category exists for a particular country.

  • localeOptional. The desired language, consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore. For example: es_MX, meaning “Spanish (Mexico)”. Provide this parameter if you want the category strings returned in a particular language. Note that, if locale is not supplied, or if the specified language is not available, the category strings returned will be in the Spotify default language (American English).

category_playlists(category_id, country=None, limit=20, offset=0)[source]

Get a list of Spotify playlists tagged with a particular category. https://developer.spotify.com/documentation/web-api/reference/browse/get-categorys-playlists/

Parameters
  • category_id – The Spotify category ID for the category.

  • countryOptional. A country: an ISO 3166-1 alpha-2 country code.

  • limitOptional. The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

  • offsetOptional. The index of the first item to return. Default: 0 (the first object). Use with limit to get the next set of items.

categories(country=None, locale=None, limit=20, offset=0)[source]

Get a list of categories used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab). https://developer.spotify.com/documentation/web-api/reference/browse/get-list-categories/

Parameters
  • countryOptional. A country: an ISO 3166-1 alpha-2 country code. Provide this parameter if you want to narrow the list of returned categories to those relevant to a particular country. If omitted, the returned items will be globally relevant.

  • localeOptional. The desired language, consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore. For example: es_MX, meaning “Spanish (Mexico)”. Provide this parameter if you want the category metadata returned in a particular language. Note that, if locale is not supplied, or if the specified language is not available, all strings will be returned in the Spotify default language (American English). The locale parameter, combined with the country parameter, may give odd results if not carefully matched. For example country=SE&locale=de_DE will return a list of categories relevant to Sweden but as German language strings.

  • limitOptional. The maximum number of categories to return. Default: 20. Minimum: 1. Maximum: 50.

  • offsetOptional. The index of the first item to return. Default: 0 (the first object). Use with limit to get the next set of categories.

featured_playlists(locale=None, country=None, timestamp=None, limit=20, offset=0)[source]

Get a list of Spotify featured playlists (shown, for example, on a Spotify player’s ‘Browse’ tab). https://developer.spotify.com/documentation/web-api/reference/browse/get-list-featured-playlists/

Parameters
  • localeOptional. The desired language, consisting of a lowercase ISO 639-1 language code and an uppercase ISO 3166-1 alpha-2 country code, joined by an underscore. For example: es_MX, meaning “Spanish (Mexico)”. Provide this parameter if you want the results returned in a particular language (where available). Note that, if locale is not supplied, or if the specified language is not available, all strings will be returned in the Spotify default language (American English). The locale parameter, combined with the country parameter, may give odd results if not carefully matched. For example country=SE&locale=de_DE will return a list of categories relevant to Sweden but as German language strings.

  • countryOptional. A country: an ISO 3166-1 alpha-2 country code. Provide this parameter if you want the list of returned items to be relevant to a particular country. If omitted, the returned items will be relevant to all countries.

  • timestampOptional. A timestamp in ISO 8601 format: yyyy-MM-ddTHH:mm:ss. Use this parameter to specify the user’s local time to get results tailored for that specific date and time in the day. If not provided, the response_args defaults to the current UTC time. Example: “2014-10-23T09:00:00” for a user whose local time is 9AM. If there were no featured playlists (or there is no data) at the specified time, the response_args will revert to the current UTC time.

  • limitOptional. The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

  • offsetOptional. The index of the first item to return. Default: 0 (the first object). Use with limit to get the next set of items.

new_releases(country=None, limit=20, offset=0)[source]

Get a list of new album releases featured in Spotify (shown, for example, on a Spotify player’s “Browse” tab). https://developer.spotify.com/documentation/web-api/reference/browse/get-list-new-releases/

Parameters
  • countryOptional. A country: an ISO 3166-1 alpha-2 country code. Provide this parameter if you want the list of returned items to be relevant to a particular country. If omitted, the returned items will be relevant to all countries.

  • limitOptional. The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

  • offsetOptional. The index of the first item to return. Default: 0 (the first object). Use with limit to get the next set of items.

recommendations(limit=20, market=None, seed_artists=None, seed_genres=None, seed_tracks=None, **filters)[source]

Create a playlist-style listening experience based on seed artists, tracks and genres. https://developer.spotify.com/documentation/web-api/reference/browse/get-recommendations/

Parameters
  • limitOptional. The target size of the list of recommended tracks. For seeds with unusually small pools or when highly restrictive filtering is applied, it may be impossible to generate the requested number of recommended tracks. Debugging information for such cases is available in the response_args. Default: 20. Minimum: 1. Maximum: 100.

  • marketOptional. An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking. Because min_*, max_* and target_* are applied to pools before relinking, the generated results may not precisely match the filters applied. Original, non-relinked tracks are available via the linked_from attribute of the relinked track response_args.

  • seed_artists (list or string of comma-separated values) – List of the Spotify IDs of the seed artists. Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks and seed_genres.

  • seed_genres (list or string of comma-separated values) – A list of any genres in the set of available genre seeds. Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks and seed_genres.

  • seed_tracks (list or string of comma-separated values) – A list of Spotify IDs for a seed track. Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks and seed_genres.

  • **filters

    Open the endpoint URL above for the complete list of tunable attributes (at the bottom of the page). Filters are of three types:

    • max_{attribute}: a hard ceiling on the selected track attribute’s value, e.g. max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.

    • min_{attribute}:

      e.g. min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.

    • target_{attribute}:

      tracks with the attribute values nearest to the target values will be preferred, e.g. you might request target_energy=0.6 and target_danceability=0.8; all target values will be weighed equally in ranking results.

user_is_following(obj_type, ids)[source]

Check to see if the current user is following one or more artists or Spotify users. https://developer.spotify.com/documentation/web-api/reference/follow/check-current-user-follows/

Relevant authorization scopes: user-follow-read

Parameters
  • obj_type – either ‘artist’ or ‘user’

  • ids (list of IDs or string of comma-separated artist IDs) –

user_is_following_users(ids)[source]

Check to see if the current user is following one or more Spotify users. https://developer.spotify.com/documentation/web-api/reference/follow/check-current-user-follows/

Relevant authorization scopes: user-follow-read

Parameters

ids (list of IDs or string of comma-separated users IDs) –

user_is_following_artists(ids)[source]

Check to see if the current user is following one or more Spotify artists. https://developer.spotify.com/documentation/web-api/reference/follow/check-current-user-follows/

Relevant authorization scopes: user-follow-read

Parameters

ids (list of IDs or string of comma-separated users IDs) –

playlist_is_followed_by(playlist_id, user_ids)[source]

Check to see if one or more Spotify users are following a specified playlist. https://developer.spotify.com/documentation/web-api/reference/follow/check-user-following-playlist/

Relevant authorization scopes: playlist-read-private

Parameters
  • playlist_id – The Spotify ID of the playlist.

  • user_idsRequired. A list of Spotify User IDs ; the ids of the users that you want to check to see if they follow the playlist. Maximum: 5 ids.

Returns

dictionary id -> True/False

follow(obj_type, ids)[source]

Add the current user as a follower of one or more artists or other Spotify users. https://developer.spotify.com/documentation/web-api/reference/follow/follow-artists-users/

Relevant authorization scopes: user-follow-modify

Parameters
  • obj_typeRequired. The ID type: either artist or user.

  • ids (list of Spotify ID strings) – Optional. A list of the artist or user Spotify IDs. A maximum of 50 IDs can be sent in one request

follow_artists(artist_ids)[source]
follow_users(user_ids)[source]
follow_playlist(playlist_id, public=True)[source]

Add the current user as a follower of a playlist. https://developer.spotify.com/documentation/web-api/reference/follow/follow-playlist/

Relevant authorization scopes: playlist-modify-public, playlist-modify-private

Parameters
  • playlist_id – The Spotify ID of the playlist. Any playlist can be followed, regardless of its public/private status, as long as you know its playlist ID.

  • public (Boolean) – Optional. Defaults to true. If true the playlist will be included in user’s public playlists, if false it will remain private. To be able to follow playlists privately, the user must have granted the playlist-modify-private scope.

user_followed_artists(obj_type, limit=20, after=None)[source]

Get the current user’s followed artists. https://developer.spotify.com/documentation/web-api/reference/follow/get-followed/

Relevant authorization scopes: user-follow-read

Parameters
  • obj_typeRequired. The ID type: currently only artist is supported.

  • limitOptional. The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

  • afterOptional. The last artist ID retrieved from the previous request.

unfollow(obj_type, ids)[source]

Remove the current user as a follower of one or more artists or other Spotify users. https://developer.spotify.com/documentation/web-api/reference/follow/unfollow-artists-users/

Relevant authorization scopes: user-follow-modify

Parameters
  • obj_typeRequired. The ID type: either artist or user.

  • ids (list of Spotify ID strings) – A list of the artist or user Spotify IDs. A maximum of 50 IDs can be sent in one request

unfollow_artists(artist_ids)[source]
unfollow_users(user_ids)[source]
unfollow_playlist(playlist_id)[source]

Remove the current user as a follower of a playlist. https://developer.spotify.com/documentation/web-api/reference/follow/unfollow-playlist/

Relevant authorization scopes: playlist-modify-public, playlist-modify-private

Parameters

playlist_id – The Spotify ID of the playlist that is to be no longer followed.

user_saved_albums_contains(album_ids)[source]

Check if one or more albums is already saved in the current Spotify user’s ‘Your Music’ library. https://developer.spotify.com/documentation/web-api/reference/library/check-users-saved-albums/

Relevant authorization scopes: user-library-read

Parameters

album_ids – Maximum: 50 IDs.

Returns

dictionary album_id -> bool(the album is between the user saved albums)

user_saved_tracks_contains(track_ids)[source]

Check if one or more tracks is already saved in the current Spotify user’s ‘Your Music’ library. https://developer.spotify.com/documentation/web-api/reference/library/check-users-saved-tracks/

Relevant authorization scopes: user-library-read

Parameters

track_ids – Maximum: 50 IDs.

Returns

dictionary track_id -> bool(the track is between the user saved tracks)

user_saved_albums(limit=20, offset=0, market=None)[source]

Get a list of the albums saved in the current Spotify user’s ‘Your Music’ library. https://developer.spotify.com/documentation/web-api/reference/library/get-users-saved-albums/

Relevant authorization scopes: user-library-read

Parameters
  • limitOptional. The maximum number of objects to return. Default: 20. Minimum: 1. Maximum: 50.

  • offsetOptional. The index of the first object to return. Default: 0 (i.e., the first object). Use with limit to get the next set of objects.

  • marketOptional. An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking.

user_saved_tracks(limit=20, offset=0, market=None)[source]

Get a list of the songs saved in the current Spotify user’s ‘Your Music’ library. https://developer.spotify.com/documentation/web-api/reference/library/get-users-saved-tracks/

Relevant authorization scopes: user-library-read

Parameters
  • limitOptional. The maximum number of objects to return. Default: 20. Minimum: 1. Maximum: 50.

  • offsetOptional. The index of the first object to return. Default: 0 (i.e., the first object). Use with limit to get the next set of objects.

  • marketOptional. An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking.

remove_albums_from_library(ids=None)[source]

Remove one or more albums from the current user’s ‘Your Music’ library. https://developer.spotify.com/documentation/web-api/reference/library/remove-albums-user/

Relevant authorization scopes: user-library-modify

Parameters

ids – Maximum: 50 IDs.

remove_tracks_from_library(ids=None)[source]

Remove one or more tracks from the current user’s ‘Your Music’ library. https://developer.spotify.com/documentation/web-api/reference/library/remove-tracks-user/

Relevant authorization scopes: user-library-modify

Parameters

ids – Maximum: 50 IDs.

save_albums_to_library(ids=None)[source]

Save one or more albums to the current user’s ‘Your Music’ library. https://developer.spotify.com/documentation/web-api/reference/library/save-albums-user/

Relevant authorization scopes: user-library-modify

Parameters

ids – Maximum: 50 IDs.

save_tracks_to_library(ids=None)[source]

Save one or more tracks to the current user’s ‘Your Music’ library. https://developer.spotify.com/documentation/web-api/reference/library/save-tracks-user/

Relevant authorization scopes: user-library-modify

Parameters

ids – Maximum: 50 IDs.

user_top(obj_type, limit=20, offset=0, time_range='medium_term')[source]

Get the current user’s top artists or tracks based on calculated affinity. https://developer.spotify.com/documentation/web-api/reference/personalization/get-users-top-artists-and-tracks/

Relevant authorization scopes: user-top-read

Parameters
  • obj_type – The type of entity to return. Valid values: artists or tracks.

  • limitOptional. The number of entities to return. Default: 20. Minimum: 1. Maximum: 50. For example: limit=2

  • offsetOptional. The index of the first entity to return. Default: 0 (i.e., the first track). Use with limit to get the next set of entities.

  • time_rangeOptional. Over what time frame the affinities are computed. Valid values: long_term (calculated from several years of data and including all new data as it becomes available), medium_term (approximately last 6 months), short_term (approximately last 4 weeks). Default: medium_term.

user_top_artists(limit=20, offset=0, time_range='medium_term')[source]

Get the current user’s top artists based on calculated affinity. https://developer.spotify.com/documentation/web-api/reference/personalization/get-users-top-artists-and-tracks/

Relevant authorization scopes: user-top-read

Parameters
  • limitOptional. The number of entities to return. Default: 20. Minimum: 1. Maximum: 50. For example: limit=2

  • offsetOptional. The index of the first entity to return. Default: 0 (i.e., the first track). Use with limit to get the next set of entities.

  • time_rangeOptional. Over what time frame the affinities are computed. Valid values: long_term (calculated from several years of data and including all new data as it becomes available), medium_term (approximately last 6 months), short_term (approximately last 4 weeks). Default: medium_term.

user_top_tracks(limit=20, offset=0, time_range='medium_term')[source]

Get the current user’s top tracks based on calculated affinity. https://developer.spotify.com/documentation/web-api/reference/personalization/get-users-top-artists-and-tracks/

Relevant authorization scopes: user-top-read

Parameters
  • limitOptional. The number of entities to return. Default: 20. Minimum: 1. Maximum: 50. For example: limit=2

  • offsetOptional. The index of the first entity to return. Default: 0 (i.e., the first track). Use with limit to get the next set of entities.

  • time_rangeOptional. Over what time frame the affinities are computed. Valid values: long_term (calculated from several years of data and including all new data as it becomes available), medium_term (approximately last 6 months), short_term (approximately last 4 weeks). Default: medium_term.

available_devices()[source]

Get information about a user’s available devices. https://developer.spotify.com/documentation/web-api/reference/player/get-a-users-available-devices/

Relevant authorization scopes: user-read-playback-state

playback_state(market=None)[source]

Get information about the user’s current playback state, including track, track progress, and active device. https://developer.spotify.com/documentation/web-api/reference/player/get-information-about-the-users-current-playback/

Relevant authorization scopes: user-read-playback-state

Parameters

marketOptional. An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking.

user_recently_played_tracks(limit=20, after=None, before=None)[source]

Get tracks from the current user’s recently played tracks. https://developer.spotify.com/documentation/web-api/reference/player/get-recently-played/

Relevant authorization scopes: user-read-recently-played

Parameters
  • limitOptional. The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

  • afterOptional. A Unix timestamp in milliseconds. Returns all items after (but not including) this cursor position. If after is specified, before must not be specified.

  • beforeOptional. A Unix timestamp in milliseconds. Returns all items before (but not including) this cursor position. If before is specified, after must not be specified.

currently_playing_track(market=None)[source]

Get the object currently being played on the user’s Spotify account. https://developer.spotify.com/documentation/web-api/reference/player/get-the-users-currently-playing-track/

Relevant authorization scopes: user-read-currently-playing, user-read-playback-state

Parameters

marketOptional. An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking.

pause(device_id=None)[source]

Pause playback on the user’s account. https://developer.spotify.com/documentation/web-api/reference/player/pause-a-users-playback/

Relevant authorization scopes: user-modify-playback-state

Parameters

device_idOptional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

seek(position_ms, device_id=None)[source]

Seeks to the given position in the user’s currently playing track. https://developer.spotify.com/documentation/web-api/reference/player/seek-to-position-in-currently-playing-track/

Relevant authorization scopes: user-modify-playback-state

Parameters
  • position_msRequired. The position in milliseconds to seek to. Must be a positive number. Passing in a position that is greater than the length of the track will cause the player to start playing the next song.

  • device_idOptional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

set_repeat_mode(state, device_id=None)[source]

Set the repeat mode for the user’s playback. Options are repeat-track, repeat-context, and off. https://developer.spotify.com/documentation/web-api/reference/player/set-repeat-mode-on-users-playback/

Relevant authorization scopes: user-modify-playback-state

Parameters
  • state"track", "context" or "off". "track" will repeat the current track. "context" will repeat the current context. "off" will turn repeat off

  • device_idOptional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

set_volume(volume_percent, device_id=None)[source]

Set the volume for the user’s current playback device. https://developer.spotify.com/documentation/web-api/reference/player/set-volume-for-users-playback/

Relevant authorization scopes: user-modify-playback-state

Parameters
  • volume_percentRequired. Integer. The volume to set. Must be a value from 0 to 100 inclusive.

  • device_idOptional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

skip_to_next_track(device_id=None)[source]

Skips to next track in the user’s queue. https://developer.spotify.com/documentation/web-api/reference/player/skip-users-playback-to-next-track/

Relevant authorization scopes: user-modify-playback-state

Parameters

device_idOptional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

skip_to_previous_track(device_id=None)[source]

Skips to previous track in the user’s queue. https://developer.spotify.com/documentation/web-api/reference/player/skip-users-playback-to-previous-track/

Relevant authorization scopes: user-modify-playback-state

Parameters

device_idOptional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

play(device_id=None, context_uri=None, uris=None, start_from=0, position_ms=None)[source]

Start a new context or resume current playback on the user’s active device. https://developer.spotify.com/documentation/web-api/reference/player/start-a-users-playback/

Relevant authorization scopes: user-modify-playback-state

Parameters
  • device_idOptional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

  • context_uri (string) – Optional. Spotify URI of the context to play. Valid contexts are albums, artists, playlists.

  • uris (list of URIs) – Optional. A list of the Spotify track URIs to play

  • start_from (int or str) –

    Optional. Indicates from where in the context playback should start. Only available when context_uri corresponds to an album or playlist object, or when the uris parameter is used. It can be provided

    • as an integer - the position of the track from which to start

    • or as a string - the Spotify URI of the track from which to start.

  • position_ms (integer) – Optional. Indicates from what position to start playback. Must be a positive number. Passing in a position that is greater than the length of the track will cause the player to start playing the next song.

toggle_shuffle(state, device_id=None)[source]

Toggle shuffle on or off for user’s playback. https://developer.spotify.com/documentation/web-api/reference/player/toggle-shuffle-for-users-playback/

Relevant authorization scopes: user-modify-playback-state

Parameters
  • stateRequired true : Shuffle user’s playback false : Do not shuffle user’s playback.

  • device_idOptional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

transfer_user_playback(device_ids, play=None)[source]

Transfer playback to a new device and determine if it should start playing. https://developer.spotify.com/documentation/web-api/reference/player/transfer-a-users-playback/

Relevant authorization scopes: user-modify-playback-state

Parameters
  • device_ids (list of Spotify Device IDs) – Required. A list containing the ID of the device on which playback should be started/transferred. For example: {device_ids:["74ASZWbe4lXaubB36ztrGX"]} Note: Although an list is accepted, only a single device_id is currently supported. Supplying more than one will return 400 Bad Request

  • play (boolean) – True: ensure playback happens on new device. False or None: keep the current playback state.

add_tracks_to_playlist(playlist_id, uris=None, position=None)[source]

Add one or more tracks to a user’s playlist. https://developer.spotify.com/documentation/web-api/reference/playlists/add-tracks-to-playlist/

Relevant authorization scopes: playlist-modify-public, playlist-modify-private

Parameters
  • playlist_id – The Spotify ID for the playlist.

  • uris (list of Spotify URI strings) – Optional. A list of the Spotify track URIs to add

  • position (integer) – Optional. The position to insert the tracks, a zero-based index. If omitted, the tracks will be appended to the playlist.

change_playlist_details(playlist_id, name=None, public=None, collaborative=None, description=None)[source]

Change a playlist’s name and public/private state. (The user must, of course, own the playlist.) https://developer.spotify.com/documentation/web-api/reference/playlists/change-playlist-details/

Relevant authorization scopes: playlist-modify-public, playlist-modify-private

Parameters
  • playlist_id – The Spotify ID for the playlist.

  • name (string) – Optional. The new name for the playlist, for example "My New Playlist Title".

  • public (Boolean) – Optional. If true the playlist will be public, if false it will be private.

  • collaborative (Boolean) – Optional. If true , the playlist will become collaborative and other users will be able to modify the playlist in their Spotify client. Note: You can only set ``collaborative`` to ``true`` on non-public playlists.

  • description (string) – Optional. Value for playlist description as displayed in Spotify Clients and in the Web API.

create_playlist(user_id, name, public=True, collaborative=False, description=None)[source]

Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.) https://developer.spotify.com/documentation/web-api/reference/playlists/create-playlist/

Relevant authorization scopes: playlist-modify-public, playlist-modify-private

Parameters
  • user_id – The user’s Spotify user ID.

  • name (string) – Required. The name for the new playlist, for example "Your Coolest Playlist" . This name does not need to be unique; a user may have several playlists with the same name.

  • public (Boolean) – Optional. Defaults to True . If true the playlist will be public, if False it will be private. To be able to create private playlists, the user must have granted the playlist-modify-private scope .

  • collaborative (Boolean) – Optional. Defaults to False . If true the playlist will be collaborative. Note that to create a collaborative playlist you must also set public to False . To create collaborative playlists you must have granted playlist-modify-private and playlist-modify-public scopes .

  • description (string) – Optional. value for playlist description as displayed in Spotify Clients and in the Web API.

current_user_playlists(limit=20, offset=0)[source]

Get a list of the playlists owned or followed by the current Spotify user. https://developer.spotify.com/documentation/web-api/reference/playlists/get-a-list-of-current-users-playlists/

Relevant authorization scopes: playlist-read-private, playlist-read-collaborative

Parameters
  • limitOptional. The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50.

  • offsetOptional. The index of the first playlist to return. Default: 0 (the first object). Maximum offset: 100.000. Use with limit to get the next set of playlists.

user_playlists(user_id, limit=20, offset=0)[source]

Get a list of the playlists owned or followed by a Spotify user. https://developer.spotify.com/documentation/web-api/reference/playlists/get-list-users-playlists/

Relevant authorization scopes: playlist-read-private, playlist-read-collaborative

Parameters
  • user_id – The user’s Spotify user ID.

  • limitOptional. The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50.

  • offsetOptional. The index of the first playlist to return. Default: 0 (the first object). Maximum offset: 100.000. Use with limit to get the next set of playlists.

playlist_cover_image(playlist_id)[source]

Get the current image associated with a specific playlist. https://developer.spotify.com/documentation/web-api/reference/playlists/get-playlist-cover/

Parameters

playlist_id – The Spotify ID for the playlist.

playlist(playlist_id, fields=None, market=None)[source]

Get a playlist owned by a Spotify user. https://developer.spotify.com/documentation/web-api/reference/playlists/get-playlist/

Parameters
  • playlist_id – The Spotify ID for the playlist.

  • fieldsOptional. Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the playlist’s description and URI: fields=description,uri. A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. For example, to get just the added date and user ID of the adder: fields="tracks.items(added_at,added_by.id)". Use multiple parentheses to drill down into nested objects, for example: fields="tracks.items(track(name,href,album(name,href)))". Fields can be excluded by enclosing them inside parenthesis starting with an exclamation mark, e.g. (!field1,field2)

  • marketOptional. An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking.

playlist_tracks(playlist_id, fields=None, limit=100, offset=0, market=None)[source]

Get full details of the tracks of a playlist owned by a Spotify user. https://developer.spotify.com/documentation/web-api/reference/playlists/get-playlists-tracks/

Parameters
  • playlist_id – The Spotify ID for the playlist.

  • fieldsOptional. Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the total number of tracks and the request limit: fields=total,limit A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. For example, to get just the added date and user ID of the adder: fields=items(added_at,added_by.id) Use multiple parentheses to drill down into nested objects, for example: fields=items(track(name,href,album(name,href))) Fields can be excluded by prefixing them with an exclamation mark, for example: fields=items.track.album(!external_urls,images)

  • limitOptional. The maximum number of tracks to return. Default: 100. Minimum: 1. Maximum: 100.

  • offsetOptional. The index of the first track to return. Default: 0 (the first object).

  • marketOptional. An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking.

remove_tracks_from_playlist(playlist_id)[source]

Remove one or more tracks from a user’s playlist. https://developer.spotify.com/documentation/web-api/reference/playlists/remove-tracks-playlist/

Relevant authorization scopes: playlist-modify-public, playlist-modify-private

Parameters

playlist_id – The Spotify ID for the playlist.

reorder_playlist_tracks(playlist_id, range_start, insert_before, range_length=1, snapshot_id=None)[source]

Reorder a track or a group of tracks in a playlist. https://developer.spotify.com/documentation/web-api/reference/playlists/reorder-playlists-tracks/

Relevant authorization scopes: playlist-modify-public, playlist-modify-private

Parameters
  • playlist_id – The Spotify ID for the playlist.

  • range_start (integer) – Required. The position of the first track to be reordered.

  • insert_before (integer) – Required. The position where the tracks should be inserted. To reorder the tracks to the end of the playlist, simply set insert_before to the position after the last track. Examples: To reorder the first track to the last position in a playlist with 10 tracks, set range_start to 0, and insert_before to 10. To reorder the last track in a playlist with 10 tracks to the start of the playlist, set range_start to 9, and insert_before to 0.

  • range_length (integer) – Optional. The amount of tracks to be reordered. Defaults to 1 if not set. The range of tracks to be reordered begins from the range_start position, and includes the range_length subsequent tracks. Example: To move the tracks at index 9-10 to the start of the playlist, range_start is set to 9, and range_length is set to 2.

  • snapshot_id (string) – Optional. The playlist’s snapshot ID against which you want to make the changes.

replace_playlist_tracks(playlist_id, uris=None)[source]

Replace all the tracks in a playlist, overwriting its existing tracks. This powerful request can be useful for replacing tracks, re-ordering existing tracks, or clearing the playlist. https://developer.spotify.com/documentation/web-api/reference/playlists/replace-playlists-tracks/

Relevant authorization scopes: playlist-modify-public, playlist-modify-private

Parameters
upload_playlist_cover_image(playlist_id)[source]

Replace the image used to represent a specific playlist. https://developer.spotify.com/documentation/web-api/reference/playlists/upload-custom-playlist-cover/

Relevant authorization scopes: playlist-modify-public, playlist-modify-private

Parameters

playlist_id – The Spotify ID for the playlist.

search(query, obj_type, market=None, limit=20, offset=0, include_external=None)[source]

Get Spotify Catalog information about artists, albums, tracks or playlists that match a keyword string. https://developer.spotify.com/documentation/web-api/reference/search/search/

Parameters
  • queryRequired. Search query keywords and optional field filters and operators. For example: query=roadhouse%20blues.

  • obj_typeRequired. A comma-separated list of item types to search across. Valid types are: album , artist, playlist, and track. Search results include hits from all the specified item types. For example: query=name:abacab&type=album,track returns both albums and tracks with “abacab” included in their name.

  • marketOptional. An ISO 3166-1 alpha-2 country code or the string from_token. If a country code is specified, only artists, albums, and tracks with content that is playable in that market is returned. Note: - Playlist results are not affected by the market parameter. - If market is set to from_token, and a valid access token is specified in the request header, only content playable in the country associated with the user account, is returned. - Users can view the country that is associated with their account in the account settings. A user must grant access to the user-read-private scope prior to when the access token is issued.

  • limitOptional. Maximum number of results to return. Default: 20 Minimum: 1 Maximum: 50 Note: The limit is applied within each type, not on the total response_args. For example, if the limit value is 3 and the type is artist,album, the response_args contains 3 artists and 3 albums.

  • offsetOptional. The index of the first result to return. Default: 0 (the first result). Maximum offset (including limit): 10,000. Use with limit to get the next page of search results.

  • include_externalOptional. Possible values: audio If include_external=audio is specified the response_args will include any relevant audio content that is hosted externally. By default external content is filtered out from responses.

track_audio_analysis(track_id)[source]

Get a detailed audio analysis for a single track identified by its unique Spotify ID. https://developer.spotify.com/documentation/web-api/reference/tracks/get-audio-analysis/

Parameters

track_idRequired. The Spotify ID for the track.

track_audio_features(track_id)[source]

Get audio feature information for a single track identified by its unique Spotify ID. https://developer.spotify.com/documentation/web-api/reference/tracks/get-audio-features/ https://developer.spotify.com/documentation/web-api/reference/tracks/get-audio-features/

Parameters

track_idRequired. The Spotify ID for the track.

tracks_audio_features(track_ids)[source]

Get audio features for multiple tracks based on their Spotify IDs. https://developer.spotify.com/documentation/web-api/reference/tracks/get-several-audio-features/

Parameters

track_idsRequired. A list of the Spotify IDs for the tracks. Maximum: 100 IDs.

tracks(ids, market=None)[source]

Get Spotify catalog information for multiple tracks based on their Spotify IDs. https://developer.spotify.com/documentation/web-api/reference/tracks/get-several-tracks/

Parameters
track(track_id, market=None)[source]

Get Spotify catalog information for a single track identified by its unique Spotify ID. https://developer.spotify.com/documentation/web-api/reference/tracks/get-track/

Parameters
current_user()[source]

Get detailed profile information about the current user (including the current user’s username). https://developer.spotify.com/documentation/web-api/reference/users-profile/get-current-users-profile/

Relevant authorization scopes: user-read-email, user-read-private, user-read-birthdate

me()[source]

Get detailed profile information about the current user (including the current user’s username). https://developer.spotify.com/documentation/web-api/reference/users-profile/get-current-users-profile/

Relevant authorization scopes: user-read-email, user-read-private, user-read-birthdate

user_public_profile(user_id)[source]

Get public profile information about a Spotify user. https://developer.spotify.com/documentation/web-api/reference/users-profile/get-users-profile/

Parameters

user_id – The user’s Spotify user ID.

class spotipie.AuthorizationCodeSession(client_id, client_secret, redirect_uri, scope=None, auto_refresh=True, **kwargs)[source]

Bases: spotipie.auth.sessions.RefreshableOAuth2Session

Session for authorization code flow

FLOW: spotipie.auth.sessions.Flow = 'authorization_code'
authorization_url(force_dialog=False, **kwargs)[source]

Generates the URL the user has to visit in order to authorize (the application using) this session. The “state” parameter (useful for security reasons) is automatically generated and included in the URL. This function returns the authorization url and the generated state.

Parameters
  • force_dialog (bool) – Whether or not to force the user to approve the app again if they’ve already done so. If false (default), a user who has already approved the application may be automatically redirected to the URI specified by redirect_uri. If True, the user will not be automatically redirected and will have to approve the app again.

  • **kwargs – other query arguments to include in the authorization URLs; at the moment of writing this functions, no other parameter exists.

Return type

Tuple[str, str]

Returns

tuple(authorization_url, state)

fetch_token(callback_url, timeout=None)[source]

Extracts the code and the state parameters from the callback URL and, after having checked the correctness of the state, it makes a request to Spotify in order to exchange the authorization code for an access token.

Parameters
  • callback_url – the URL Spotify redirects to after the user grants his authorization to your app, i.e. the redirect URI with query arguments “code” and “state” (at least). The function raises an exception if the callback URL contains an “error” argument

  • timeout

Raises
  • AccessDenied – if the user decides to not grant access

  • AuthorizationException – the callback_url has an error argument different from “access_denied”

  • requests.Timeout

fetch_token_given_code(code, state, timeout=None)[source]

Variant of fetch_token() where you pass the code and state parameters directly rather than a callback URL.

class spotipie.ClientCredentialsSession(client_id, client_secret, auto_refresh=True, **kwargs)[source]

Bases: spotipie.auth.sessions.RefreshableOAuth2Session

FLOW: spotipie.auth.sessions.Flow = 'client_credentials'
fetch_token(timeout=None)[source]
class spotipie.ImplicitGrantSession(client_id, redirect_uri, scope=None, **kwargs)[source]

Bases: spotipie.auth.sessions.BaseOAuth2Session

Session following the “implicit grant flow” for authorization

FLOW: spotipie.auth.sessions.Flow = 'implicit_grant'
authorization_url(force_dialog=False, **kwargs)[source]

Generates the URL the user has to visit in order to authorize (the application using) this session. The “state” parameter (useful for security reasons) is automatically generated and included in the URL. This function returns the authorization url and the generated state.

Parameters
  • force_dialog (bool) – Whether or not to force the user to approve the app again if they’ve already done so. If false (default), a user who has already approved the application may be automatically redirected to the URI specified by redirect_uri. If True, the user will not be automatically redirected and will have to approve the app again.

  • **kwargs – other query arguments to include in the authorization URLs; at the moment of writing this functions, no other parameter exists.

Return type

Tuple[str, str]

Returns

tuple(authorization_url, state)

read_token_from_callback_url(callback_url)[source]

Parses the callback URL and grab the token information contained in the fragment of the URL. Sets the token property and returns the token.

Return type

OAuth2Token

class spotipie.Credentials(client_id, client_secret, redirect_uri)[source]

Bases: object

Method generated by attrs for class Credentials.

client_id: str
client_secret: Optional[str]
redirect_uri: str
staticmethod from_environment(prefix='SPOTIPIE')[source]

Reads Spotify OAuth2 credentials from the following environment variables: {prefix}_CLIENT_ID, {prefix}_CLIENT_SECRET, {prefix}_REDIRECT_URI.

Raises

KeyError – if no variable is defined for client_id and redirect_uri.

Return type

Credentials