Client

Web API endpoints.

API summary
Album API	Album information
Artist API	Artist information
Audiobook API	Audiobook information
Browse API	Spotify featured catalogue
Chapter API	Chapter information
Episode API	Episode information
Follow API	Follow artists, playlists and users
Library API	Save (like) albums, shows and tracks
Markets API	Spotify market information
Personalisation API	User top listens
Player API	Playback operations
Playlist API	Playlist operations
Search API	Search functionality
Show API	Show information
Track API	Track information and analysis
User API	User information

Each method of the client corresponds to an API call, with some exceptions. Further documentation on endpoints can be viewed in the Web API reference.

import tekore as tk

# Initialise the client
spotify = tk.Spotify(token)

# Call the API
album = spotify.album('3RBULTZJ97bvVzZLpxcB0j')
for track in album.tracks.items:
    print(track.track_number, track.name)

Required and optional scopes to call any endpoint can be determined in code. Endpoints provide required_scope and optional_scope attributes which return a Scope. A combination of the two is provided in scope. They can be accessed via the class itself or its instances.

scope_cls = tk.Spotify.current_user_top_tracks.scope
scope_inst = tk.Spotify().current_user_top_tracks.scope
assert scope_cls == scope_inst

class tekore.Spotify(token=None, sender=None, asynchronous=None, max_limits_on=False, chunked_on=False)

Bases: tekore.Client.

Client to Web API endpoints.

Parameters:

token – bearer token for requests
sender (Sender | None) – request sender
asynchronous (bool | None) – synchronicity requirement
max_limits_on (bool) – use maximum limits in paging calls, overrided by endpoint arguments
chunked_on (bool) – use chunking when requesting lists of resources

token: bearer token for requests

sender: underlying sender

max_limits_on: use maximum limits in paging calls, overrided by endpoint arguments

chunked_on: use chunking when requesting lists of resources

Non-endpoint methods

`Spotify.chunked`	Toggle chunking lists of resources.
`Spotify.max_limits`	Toggle using maximum limits in paging calls.
`Spotify.token_as`	Use a different token with requests.
`Spotify.follow_short_link`	Follow redirect of a short link to get the underlying resource URL.
`is_short_link`	Determine if URL is a Spotify short link.
`Spotify.send`	Build request url and headers, and send with underlying sender.
`Spotify.close`	Close the underlying sender.

Spotify.chunked(on=True)

Toggle chunking lists of resources. Context manager, async safe.

Parameters:: on (bool) – enable or disable chunking
Returns:: self as context
Return type:: Generator[Spotify, None, None]

Examples

spotify = Spotify(token)
with spotify.chunked(True):
    tracks = spotify.tracks(many_ids)

spotify = Spotify(token, chunked_on=True)
with spotify.chunked(False):
    tracks = spotify.search(many_ids[:50])

Spotify.max_limits(on=True)

Toggle using maximum limits in paging calls. Context manager, async safe.

Parameters:: on (bool) – enable or disable using maximum limits
Returns:: self as context
Return type:: Generator[Spotify, None, None]

Examples

spotify = Spotify(token)
with spotify.max_limits(True):
    tracks, = spotify.search('piano')

spotify = Spotify(token, max_limits_on=True)
with spotify.max_limits(False):
    tracks, = spotify.search('piano')

Spotify.token_as(token)

Use a different token with requests. Context manager, async safe.

Parameters:: token – access token
Returns:: self as context
Return type:: Generator[Spotify, None, None]

Examples

spotify = Spotify()
with spotify.token_as(token):
    album = spotify.album(album_id)

spotify = Spotify(app_token)
with spotify.token_as(user_token):
    user = spotify.current_user()

Spotify.follow_short_link(link)

Follow redirect of a short link to get the underlying resource URL.

Safely also accept a direct link, request a redirect and return the original URL. Also use the underlying sender for an unauthenticated request.

Returns:: result of the short link redirect
Return type:: url
Parameters:: link (str) –

tekore.is_short_link(url)

Determine if URL is a Spotify short link.

Parameters:: url (str) –
Return type:: bool

Spotify.send(request)

Build request url and headers, and send with underlying sender.

Exposed to easily send arbitrary requests, for custom behavior in some endpoint e.g. for a subclass. It may also come in handy if a bugfix or a feature is not implemented in a timely manner, or in debugging related to the client or Web API.

Parameters:: request (Request) –
Return type:: Response | Coroutine[None, None, Response]

Spotify.close()

Close the underlying sender.

To close synchronous senders, call close(). To close asynchronous senders, await close().

Return type:: None | Coroutine[None, None, None]

Paging navigation

`Spotify.next`	Retrieve the next result set of a paging object.
`Spotify.previous`	Retrieve the previous result set of a paging object.
`Spotify.all_items`	Retrieve all items from all pages of a paging.
`Spotify.all_pages`	Retrieve all pages of a paging.

Spotify.next(page)

Retrieve the next result set of a paging object.

Parameters:: page (Paging) – paging object
Returns:: next result set
Return type:: Paging

Spotify.previous(page)

Retrieve the previous result set of a paging object.

Parameters:: page (OffsetPaging) – offset-based paging object
Returns:: previous result set
Return type:: OffsetPaging

Spotify.all_items(page)

Retrieve all items from all pages of a paging.

Request and yield new (next) items until the end of the paging. The items in the paging that was given as an argument are yielded first.

Parameters:: page (Paging) – paging object
Returns:: all items within a paging
Return type:: Generator

Spotify.all_pages(page)

Retrieve all pages of a paging.

Request and yield new (next) pages until the end of the paging. The paging that was given as an argument is yielded as the first result.

Parameters:: page (Paging) – paging object
Returns:: all pages within a paging
Return type:: Generator

Album API

`Spotify.album`	Get an album.
`Spotify.album_tracks`	Get tracks on album.
`Spotify.albums`	Get multiple albums.

Spotify.album(album_id, market=None)

Get an album.

Required scope: none

Optional scope: none

Parameters:

album_id (str) – album ID
market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’

Return type:

FullAlbum

Spotify.album_tracks(album_id, market=None, limit=20, offset=0)

Get tracks on album.

Required scope: none

Optional scope: none

Parameters:

album_id (str) – album ID
market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

SimpleTrackPaging

Spotify.albums(album_ids, market=None)

Get multiple albums.

Required scope: none

Optional scope: none

Parameters:

album_ids (list[str]) – list of album IDs, max 20 without chunking
market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’

Return type:

list[FullAlbum]

Artist API

`Spotify.artist`	Get information for an artist.
`Spotify.artist_albums`	Get an artist's albums.
`Spotify.artist_related_artists`	Get artists similar to an identified artist.
`Spotify.artist_top_tracks`	Get an artist's top 10 tracks by country.
`Spotify.artists`	Get information for multiple artists.

Spotify.artist(artist_id)

Get information for an artist.

Required scope: none

Optional scope: none

Parameters:: artist_id (str) – artist ID
Return type:: FullArtist

Spotify.artist_albums(artist_id, include_groups=None, market=None, limit=20, offset=0)

Get an artist’s albums.

Required scope: none

Optional scope: none

Parameters:

artist_id (str) – the artist ID
include_groups (list[str | AlbumGroup] | None) – album groups to include in the response
market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

SimpleAlbumPaging

Spotify.artist_related_artists(artist_id)

Get artists similar to an identified artist.

Required scope: none

Optional scope: none

Warning

This endpoint is unavailable to new third-party applications (#331)

Similarity is based on analysis of the Spotify community’s listening history.

Parameters:: artist_id (str) – artist ID
Return type:: list[FullArtist]

Spotify.artist_top_tracks(artist_id, market)

Get an artist’s top 10 tracks by country.

Required scope: none

Optional scope: none

Parameters:

artist_id (str) – the artist ID
market (str) – an ISO 3166-1 alpha-2 country code or ‘from_token’

Return type:

list[FullTrack]

Spotify.artists(artist_ids)

Get information for multiple artists.

Required scope: none

Optional scope: none

Parameters:: artist_ids (list[str]) – list of artist IDs, max 50 without chunking
Return type:: list[FullArtist]

Audiobook API

`Spotify.audiobook`	Get information for an audiobook.
`Spotify.audiobook_chapters`	Get chapters of an audiobook.
`Spotify.audiobooks`	Get information for multiple audiobooks.

Spotify.audiobook(audiobook_id, market=None)

Get information for an audiobook.

Required scope: none

Optional scope: none

Parameters:

audiobook_id (str) – audiobook ID
market (str | None) – an ISO 3166-1 alpha-2 country code. If a user token is used to authenticate, the country associated with it overrides this parameter. If an application token is used and no market is specified, the show is considered unavailable.

Return type:

FullAudiobook

Spotify.audiobook_chapters(audiobook_id, market=None, limit=20, offset=0)

Get chapters of an audiobook.

Required scope: none

Optional scope: none

Parameters:

audiobook_id (str) – audiobook ID
market (str | None) – an ISO 3166-1 alpha-2 country code. If a user token is used to authenticate, the country associated with it overrides this parameter. If an application token is used and no market is specified, the show is considered unavailable.
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

SimpleChapterPaging

Spotify.audiobooks(audiobook_ids, market=None)

Get information for multiple audiobooks.

Required scope: none

Optional scope: none

Parameters:

audiobook_ids (list[str]) – the audiobook IDs, max 50 without chunking
market (str | None) – an ISO 3166-1 alpha-2 country code. If a user token is used to authenticate, the country associated with it overrides this parameter. If an application token is used and no market is specified, the show is considered unavailable.

Return type:

list[FullAudiobook]

Browse API

`Spotify.categories`	Get a list of categories used to tag items in Spotify.
`Spotify.category`	Get a single category used to tag items in Spotify.
`Spotify.category_playlists`	Get a list of Spotify playlists tagged with a particular category.
`Spotify.featured_playlists`	Get a list of Spotify featured playlists.
`Spotify.new_releases`	Get a list of new album releases featured in Spotify.
`Spotify.recommendation_genre_seeds`	Get a list of available genre seeds.
`Spotify.recommendations`	Get a list of recommended tracks for seeds.

Spotify.categories(country=None, locale=None, limit=20, offset=0)

Get a list of categories used to tag items in Spotify.

Required scope: none

Optional scope: none

Parameters:

country (str | None) – an ISO 3166-1 alpha-2 country code
locale (str | None) – the desired language, consisting of a lowercase ISO 639 language code and an uppercase ISO 3166-1 alpha-2 country code joined by an underscore
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

CategoryPaging

Spotify.category(category_id, country=None, locale=None)

Get a single category used to tag items in Spotify.

Required scope: none

Optional scope: none

Parameters:

category_id (str) – category ID
country (str | None) – an ISO 3166-1 alpha-2 country code
locale (str | None) – the desired language, consisting of a lowercase ISO 639 language code and an uppercase ISO 3166-1 alpha-2 country code joined by an underscore

Return type:

Category

Spotify.category_playlists(category_id, country=None, limit=20, offset=0)

Get a list of Spotify playlists tagged with a particular category.

Required scope: none

Optional scope: none

Warning

This endpoint is unavailable to new third-party applications (#331)

Parameters:

category_id (str) – category ID
country (str | None) – an ISO 3166-1 alpha-2 country code
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

SimplePlaylistPaging

Spotify.featured_playlists(country=None, locale=None, timestamp=None, limit=20, offset=0)

Get a list of Spotify featured playlists.

Required scope: none

Optional scope: none

Warning

This endpoint is unavailable to new third-party applications (#331)

Parameters:

country (str | None) – an ISO 3166-1 alpha-2 country code
locale (str | None) – the desired language, consisting of a lowercase ISO 639 language code and an uppercase ISO 3166-1 alpha-2 country code joined by an underscore
timestamp (str | None) – Timestamp in ISO 8601 format: yyyy-MM-ddTHH:mm:ss. Used to specify the user’s local time to get results tailored for that specific date and time in the day.
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Returns:

message and playlists

Return type:

tuple[str, SimplePlaylistPaging]

Spotify.new_releases(country=None, limit=20, offset=0)

Get a list of new album releases featured in Spotify.

Required scope: none

Optional scope: none

Parameters:

country (str | None) – an ISO 3166-1 alpha-2 country code
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

SimpleAlbumPaging

Spotify.recommendation_genre_seeds()

Get a list of available genre seeds.

Required scope: none

Optional scope: none

Return type:: list[str]

Spotify.recommendations(artist_ids=None, genres=None, track_ids=None, limit=20, market=None, **attributes)

Get a list of recommended tracks for seeds.

Required scope: none

Optional scope: none

Warning

This endpoint is unavailable to new third-party applications (#331)

Warning

The total number of seeds provided in artist_ids, genres and track_ids must be at least 1 and at most 5.

Parameters:

artist_ids (list[str] | None) – list of seed artist IDs
genres (list[str] | None) – list of seed genre names
track_ids (list[str] | None) – list of seed track IDs
limit (int) – the number of items to return (1..100)
market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’
attributes – min/max/target_<attribute> - For all tuneable track attributes see model.RecommendationAttribute, these values provide filters and targeting on results.

Raises:

ValueError – if any attribute is not allowed

Return type:

Recommendations

Chapter API

`Spotify.chapter`	Get information for a chapter.
`Spotify.chapters`	Get information for multiple chapters.

Spotify.chapter(chapter_id, market=None)

Get information for a chapter.

Required scope: none

Optional scope: none

Parameters:

chapter_id (str) – chapter ID
market (str | None) – an ISO 3166-1 alpha-2 country code. If a user token is used to authenticate, the country associated with it overrides this parameter. If an application token is used and no market is specified, the episode is considered unavailable.

Return type:

FullChapter

Spotify.chapters(chapter_ids, market=None)

Get information for multiple chapters.

Required scope: none

Optional scope: none

Parameters:

chapter_ids (list[str]) – the chapter IDs, max 50 without chunking
market (str | None) – an ISO 3166-1 alpha-2 country code. If a user token is used to authenticate, the country associated with it overrides this parameter. If an application token is used and no market is specified, the episode is considered unavailable.

Return type:

list[FullChapter]

Episode API

`Spotify.episode`	Get information for an episode.
`Spotify.episodes`	Get information for multiple episodes.

Spotify.episode(episode_id, market=None)

Get information for an episode.

Required scope: none

Optional scope: none

Parameters:

episode_id (str) – episode ID
market (str | None) – an ISO 3166-1 alpha-2 country code. If a user token is used to authenticate, the country associated with it overrides this parameter. If an application token is used and no market is specified, the episode is considered unavailable.

Return type:

FullEpisode

Spotify.episodes(episode_ids, market=None)

Get information for multiple episodes.

Required scope: none

Optional scope: none

Parameters:

episode_ids (list[str]) – the episode IDs, max 50 without chunking
market (str | None) – an ISO 3166-1 alpha-2 country code. If a user token is used to authenticate, the country associated with it overrides this parameter. If an application token is used and no market is specified, the episode is considered unavailable.

Return type:

list[FullEpisode]

Follow API

`Spotify.artists_follow`	Follow artists as current user.
`Spotify.artists_is_following`	Check if current user follows artists.
`Spotify.artists_unfollow`	Unfollow artists as current user.
`Spotify.followed_artists`	Get artists followed by the current user.
`Spotify.playlist_follow`	Follow a playlist as current user.
`Spotify.playlist_is_following`	Check if users are following a playlist.
`Spotify.playlist_unfollow`	Unfollow a playlist as current user.
`Spotify.followed_playlists`	Get a list of the playlists owned or followed by the current user.
`Spotify.users_follow`	Follow users as current user.
`Spotify.users_is_following`	Check if current user follows users.
`Spotify.users_unfollow`	Unfollow users as current user.

Spotify.artists_follow(artist_ids)

Follow artists as current user.

Required scope: user-follow-modify

Optional scope: none

Parameters:: artist_ids (list[str]) – list of artist IDs, max 50 without chunking
Return type:: None

Spotify.artists_is_following(artist_ids)

Check if current user follows artists.

Required scope: user-follow-read

Optional scope: none

Parameters:: artist_ids (list[str]) – list of artist IDs, max 50 without chunking
Returns:: follow statuses in the same order that the artist IDs were given
Return type:: list[bool]

Spotify.artists_unfollow(artist_ids)

Unfollow artists as current user.

Required scope: user-follow-modify

Optional scope: none

Parameters:: artist_ids (list[str]) – list of artist IDs, max 50 without chunking
Return type:: None

Spotify.followed_artists(limit=20, after=None)

Get artists followed by the current user.

Required scope: user-follow-read

Optional scope: none

Parameters:

limit (int) – the number of items to return (1..50)
after (str | None) – the last artist ID retrieved from the previous request

Return type:

FullArtistCursorPaging

Spotify.playlist_follow(playlist_id, public=True)

Follow a playlist as current user.

Required scope: playlist-modify-public

Optional scope: playlist-modify-private

Parameters:

playlist_id (str) – playlist ID
public (bool) – follow publicly

Return type:

None

Spotify.playlist_is_following(playlist_id, user_ids)

Check if users are following a playlist.

Required scope: none

Optional scope: playlist-read-private

Parameters:

playlist_id (str) – playlist ID
user_ids (list[str]) – list of user IDs, max 5 without chunking

Returns:

follow statuses in the same order that the user IDs were given

Return type:

list[bool]

Spotify.playlist_unfollow(playlist_id)

Unfollow a playlist as current user.

Required scope: playlist-modify-public

Optional scope: playlist-modify-private

Parameters:: playlist_id (str) – playlist ID
Return type:: None

Spotify.followed_playlists(limit=20, offset=0)

Get a list of the playlists owned or followed by the current user.

Required scope: none

Optional scope: playlist-read-collaborative playlist-read-private

Parameters:

limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

SimplePlaylistPaging

Spotify.users_follow(user_ids)

Follow users as current user.

Required scope: user-follow-modify

Optional scope: none

Parameters:: user_ids (list[str]) – list of user IDs, max 50 without chunking
Return type:: None

Spotify.users_is_following(user_ids)

Check if current user follows users.

Required scope: user-follow-read

Optional scope: none

Parameters:: user_ids (list[str]) – list of user IDs, max 50 without chunking
Returns:: follow statuses in the same order that the user IDs were given
Return type:: list[bool]

Spotify.users_unfollow(user_ids)

Unfollow users as current user.

Required scope: user-follow-modify

Optional scope: none

Parameters:: user_ids (list[str]) – list of user IDs, max 50 without chunking
Return type:: None

Library API

`Spotify.saved_albums`	Get the albums saved in the current user's library.
`Spotify.saved_albums_add`	Save albums for current user.
`Spotify.saved_albums_contains`	Check if user has saved albums.
`Spotify.saved_albums_delete`	Remove albums for current user.
`Spotify.saved_episodes`	Get the episodes saved in the current user's library.
`Spotify.saved_episodes_add`	Save episodes for current user.
`Spotify.saved_episodes_contains`	Check if user has saved episodes.
`Spotify.saved_episodes_delete`	Remove episodes for current user.
`Spotify.saved_shows`	Get the shows saved in the current user's library.
`Spotify.saved_shows_add`	Save shows for current user.
`Spotify.saved_shows_contains`	Check if user has saved shows.
`Spotify.saved_shows_delete`	Remove shows for current user.
`Spotify.saved_tracks`	Get the songs saved in the current user's library.
`Spotify.saved_tracks_add`	Save tracks for current user.
`Spotify.saved_tracks_contains`	Check if user has saved tracks.
`Spotify.saved_tracks_delete`	Remove tracks for current user.

Spotify.saved_albums(market=None, limit=20, offset=0)

Get the albums saved in the current user’s library.

Required scope: user-library-read

Optional scope: none

Parameters:

market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

SavedAlbumPaging

Spotify.saved_albums_add(album_ids)

Save albums for current user.

Required scope: user-library-modify

Optional scope: none

Parameters:: album_ids (list[str]) – list of album IDs, max 50 without chunking
Return type:: None

Spotify.saved_albums_contains(album_ids)

Check if user has saved albums.

Required scope: user-library-read

Optional scope: none

Parameters:: album_ids (list[str]) – list of album IDs, max 50 without chunking
Returns:: save statuses in the same order the album IDs were given
Return type:: list[bool]

Spotify.saved_albums_delete(album_ids)

Remove albums for current user.

Required scope: user-library-modify

Optional scope: none

Parameters:: album_ids (list[str]) – list of album IDs, max 50 without chunking
Return type:: None

Spotify.saved_episodes(market=None, limit=20, offset=0)

Get the episodes saved in the current user’s library.

Required scope: user-library-read

Optional scope: none

Parameters:

market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

SavedEpisodePaging

Spotify.saved_episodes_add(episode_ids)

Save episodes for current user.

Required scope: user-library-modify

Optional scope: none

Parameters:: episode_ids (list[str]) – list of episode IDs, max 50 without chunking
Return type:: None

Spotify.saved_episodes_contains(episode_ids)

Check if user has saved episodes.

Required scope: user-library-read

Optional scope: none

Parameters:: episode_ids (list[str]) – list of episode IDs, max 50 without chunking
Returns:: save statuses in the same order the episode IDs were given
Return type:: list[bool]

Spotify.saved_episodes_delete(episode_ids)

Remove episodes for current user.

Required scope: user-library-modify

Optional scope: none

Parameters:: episode_ids (list[str]) – list of episode IDs, max 50 without chunking
Return type:: None

Spotify.saved_shows(market=None, limit=20, offset=0)

Get the shows saved in the current user’s library.

Required scope: user-library-read

Optional scope: none

Parameters:

market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

SavedShowPaging

Spotify.saved_shows_add(show_ids)

Save shows for current user.

Required scope: user-library-modify

Optional scope: none

Parameters:: show_ids (list[str]) – list of show IDs, max 50 without chunking
Return type:: None

Spotify.saved_shows_contains(show_ids)

Check if user has saved shows.

Required scope: user-library-read

Optional scope: none

Parameters:: show_ids (list[str]) – list of show IDs, max 50 without chunking
Returns:: save statuses in the same order the show IDs were given
Return type:: list[bool]

Spotify.saved_shows_delete(show_ids, market=None)

Remove shows for current user.

Required scope: user-library-modify

Optional scope: none

Parameters:

show_ids (list[str]) – list of show IDs, max 50 without chunking
market (str | None) – an ISO 3166-1 alpha-2 country code, only remove shows that are available in the specified market, overrided by token’s country

Return type:

None

Spotify.saved_tracks(market=None, limit=20, offset=0)

Get the songs saved in the current user’s library.

Required scope: user-library-read

Optional scope: none

Parameters:

market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

SavedTrackPaging

Spotify.saved_tracks_add(track_ids)

Save tracks for current user.

Required scope: user-library-modify

Optional scope: none

Parameters:: track_ids (list[str]) – list of track IDs, max 50 without chunking
Return type:: None

Spotify.saved_tracks_contains(track_ids)

Check if user has saved tracks.

Required scope: user-library-read

Optional scope: none

Parameters:: track_ids (list[str]) – list of track IDs, max 50 without chunking
Returns:: save statuses in the same order the track IDs were given
Return type:: list[bool]

Spotify.saved_tracks_delete(track_ids)

Remove tracks for current user.

Required scope: user-library-modify

Optional scope: none

Parameters:: track_ids (list[str]) – list of track IDs, max 50 without chunking
Return type:: None

Markets API

Spotify.markets

Get available market country codes.

Spotify.markets()

Get available market country codes.

Required scope: none

Optional scope: none

Returns:: available markets
Return type:: list[str]

Personalisation API

`Spotify.current_user_top_artists`	Get the current user's top artists.
`Spotify.current_user_top_tracks`	Get the current user's top tracks.

Spotify.current_user_top_artists(time_range='medium_term', limit=20, offset=0)

Get the current user’s top artists.

Required scope: user-top-read

Optional scope: none

Parameters:

time_range (str) – Over what time frame are the affinities computed. Valid-values: short_term, medium_term, long_term
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

FullArtistOffsetPaging

Spotify.current_user_top_tracks(time_range='medium_term', limit=20, offset=0)

Get the current user’s top tracks.

Required scope: user-top-read

Optional scope: none

Parameters:

time_range (str) – Over what time frame are the affinities computed. Valid-values: short_term, medium_term, long_term
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

FullTrackPaging

Player API

`Spotify.playback`	Get information about user's current playback.
`Spotify.playback_currently_playing`	Get user's currently playing track.
`Spotify.playback_devices`	Get a user's available devices.
`Spotify.playback_next`	Skip user's playback to next track.
`Spotify.playback_pause`	Pause a user's playback.
`Spotify.playback_previous`	Skip user's playback to previous track.
`Spotify.playback_queue`	Get items in a user's queue.
`Spotify.playback_queue_add`	Add a track or an episode to a user's queue.
`Spotify.playback_recently_played`	Get tracks from the current user's recently played tracks.
`Spotify.playback_repeat`	Set repeat mode for playback.
`Spotify.playback_resume`	Resume user's playback.
`Spotify.playback_seek`	Seek to position in current playing track.
`Spotify.playback_shuffle`	Toggle shuffle for user's playback.
`Spotify.playback_start_context`	Start playback of a context: an album, artist or playlist.
`Spotify.playback_start_tracks`	Start playback of one or more tracks.
`Spotify.playback_transfer`	Transfer playback to another device.
`Spotify.playback_volume`	Set volume for user's playback.

Spotify.playback(market=None, tracks_only=False)

Get information about user’s current playback.

Required scope: user-read-playback-state

Optional scope: none

Parameters:

market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’
tracks_only (bool) – return only tracks in the currently playing item, if True, episodes have None as the currently playing item

Returns:

information about current playback

Return type:

CurrentlyPlayingContext

Spotify.playback_currently_playing(market=None, tracks_only=False)

Get user’s currently playing track.

Required scope: user-read-currently-playing user-read-playback-state

Optional scope: user-read-currently-playing user-read-playback-state

Only one of the scopes above is required.

Parameters:

market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’
tracks_only (bool) – return only tracks in the currently playing item, if True, episodes have None as the currently playing item

Returns:

information about the current track playing

Return type:

CurrentlyPlaying

Spotify.playback_devices()

Get a user’s available devices.

Required scope: user-read-playback-state

Optional scope: none

Return type:: list[Device]

Spotify.playback_next(device_id=None)

Skip user’s playback to next track.

Required scope: user-modify-playback-state

Optional scope: none

Parameters:: device_id (str | None) – device to skip track on
Return type:: None

Spotify.playback_pause(device_id=None)

Pause a user’s playback.

Required scope: user-modify-playback-state

Optional scope: none

Parameters:: device_id (str | None) – device to pause playback on
Return type:: None

Spotify.playback_previous(device_id=None)

Skip user’s playback to previous track.

Required scope: user-modify-playback-state

Optional scope: none

Parameters:: device_id (str | None) – device to skip track on
Return type:: None

Spotify.playback_queue()

Get items in a user’s queue.

Required scope: user-read-playback-state

Optional scope: none

The result also include items in the current playback context even though they are not explicitly in the queue. The number of items in the queue is inconsistent, but from manual experimentation at least two items are returned.

Return type:: Queue

Spotify.playback_queue_add(uri, device_id=None)

Add a track or an episode to a user’s queue.

Required scope: user-modify-playback-state

Optional scope: none

Parameters:

uri (str) – resource to add, track or episode
device_id (str | None) – devide to extend the queue on

Return type:

None

Spotify.playback_recently_played(limit=20, after=None, before=None)

Get tracks from the current user’s recently played tracks.

Required scope: user-read-recently-played

Optional scope: none

Only after or before should be specified at one time.

Parameters:

limit (int) – the number of items to return (1..50)
after (int | None) – a unix timestamp in milliseconds, must not be specified with ‘before’
before (int | None) – a unix timestamp in milliseconds, must not be specified with ‘after’

Return type:

PlayHistoryPaging

Spotify.playback_repeat(state, device_id=None)

Set repeat mode for playback.

Required scope: user-modify-playback-state

Optional scope: none

Parameters:

state (str | RepeatState) – track, context, or off
device_id (str | None) – device to set repeat on

Return type:

None

Spotify.playback_resume(device_id=None)

Resume user’s playback.

Required scope: user-modify-playback-state

Optional scope: none

Parameters:: device_id (str | None) – device to start playback on
Return type:: None

Spotify.playback_seek(position_ms, device_id=None)

Seek to position in current playing track.

Required scope: user-modify-playback-state

Optional scope: none

Parameters:

position_ms (int) – position on track
device_id (str | None) – device to seek on

Return type:

None

Spotify.playback_shuffle(state, device_id=None)

Toggle shuffle for user’s playback.

Required scope: user-modify-playback-state

Optional scope: none

Parameters:

state (bool) – shuffle state
device_id (str | None) – device to toggle shuffle on

Return type:

None

Spotify.playback_start_context(context_uri, offset=None, position_ms=None, device_id=None)

Start playback of a context: an album, artist or playlist.

Required scope: user-modify-playback-state

Optional scope: none

Parameters:

context_uri (str) – context to start playing
offset (int | str | None) – offset into context by index or track ID, only available when context is an album or playlist
position_ms (int | None) – initial position of first played track
device_id (str | None) – device to start playback on

Return type:

None

Spotify.playback_start_tracks(track_ids, offset=None, position_ms=None, device_id=None)

Start playback of one or more tracks.

Required scope: user-modify-playback-state

Optional scope: none

Parameters:

track_ids (list[str]) – track IDs to start playing
offset (int | str | None) – offset into tracks by index or track ID
position_ms (int | None) – initial position of first played track
device_id (str | None) – device to start playback on

Return type:

None

Spotify.playback_transfer(device_id, force_play=False)

Transfer playback to another device.

Required scope: user-modify-playback-state

Optional scope: none

Parameters:

device_id (str) – device to transfer playback to
force_play (bool) – true: play after transfer, false: keep current state

Return type:

None

Spotify.playback_volume(volume_percent, device_id=None)

Set volume for user’s playback.

Required scope: user-modify-playback-state

Optional scope: none

Parameters:

volume_percent (int) – volume to set (0..100)
device_id (str | None) – device to set volume on

Return type:

None

Playlist API

`Spotify.playlist`	Get playlist of a user.
`Spotify.playlists`	Get a list of the playlists owned or followed by a user.
`Spotify.playlist_create`	Create a playlist.
`Spotify.playlist_change_details`	Change a playlist's details.
`Spotify.playlist_cover_image`	Get cover image of a playlist.
`Spotify.playlist_cover_image_upload`	Upload a custom playlist cover image.
`Spotify.playlist_items`	Full details of items on a playlist.
`Spotify.playlist_add`	Add items.
`Spotify.playlist_clear`	Remove all items.
`Spotify.playlist_remove`	Remove items by URI.
`Spotify.playlist_reorder`	Reorder items.
`Spotify.playlist_replace`	Replace all items.

See Spotify’s guide on working with playlists for additional information.

Spotify.playlist(playlist_id, fields=None, market=None, as_tracks=False)

Get playlist of a user.

Required scope: none

Optional scope: none

Note

Returns a dictionary if fields or as_tracks is specified.

Parameters:

playlist_id (str) – playlist ID
fields (str | None) – which fields to return, see the Web API documentation for details
market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’ when using a user token to authenticate. For episodes in the playlist, if a user token is used, the country associated with it overrides this parameter. If an application token is used and no market is specified, episodes are considered unavailable and returned as None.
as_tracks (bool | Iterable[str]) – return types of items with track-like fields. If True, return all other types as tracks. If an iterable is passed, types contained are returned as tracks. Currently the only extra type is episode.

Returns:

playlist object, or raw dictionary if fields or as_tracks was specified

Return type:

FullPlaylist | dict

Spotify.playlists(user_id, limit=20, offset=0)

Get a list of the playlists owned or followed by a user.

Required scope: none

Optional scope: playlist-read-collaborative playlist-read-private

Collaborative playlists are only returned for the current user.

Parameters:

user_id (str) – user ID
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

SimplePlaylistPaging

Spotify.playlist_create(user_id, name, public=True, description='')

Create a playlist.

Required scope: playlist-modify-public

Optional scope: playlist-modify-private

Parameters:

user_id (str) – user ID
name (str) – the name of the playlist
public (bool) – is the created playlist public
description (str) – the description of the playlist

Return type:

FullPlaylist

Spotify.playlist_change_details(playlist_id, name=None, public=None, collaborative=None, description=None)

Change a playlist’s details.

Required scope: playlist-modify-public

Optional scope: playlist-modify-private

Parameters:

playlist_id (str) – playlist ID
name (str | None) – name of the playlist
public (bool | None) – is the playlist public
collaborative (bool | None) – is the playlist collaborative
description (str | None) – description of the playlist

Return type:

None

Spotify.playlist_cover_image(playlist_id)

Get cover image of a playlist.

Required scope: none

Optional scope: none

Note

Returns a list of images.

Parameters:: playlist_id (str) – playlist ID
Return type:: list[Image]

Spotify.playlist_cover_image_upload(playlist_id, image)

Upload a custom playlist cover image.

Required scope: playlist-modify-public ugc-image-upload

Optional scope: playlist-modify-private

Parameters:

playlist_id (str) – playlist ID
image (str) – image data as a base64-encoded string

Return type:

None

Spotify.playlist_items(playlist_id, fields=None, market=None, as_tracks=False, limit=100, offset=0)

Full details of items on a playlist.

Required scope: none

Optional scope: none

Note

Returns a dictionary if fields or as_tracks is specified.

Parameters:

playlist_id (str) – playlist ID
fields (str | None) – which fields to return, see the Web API documentation for details
market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’ when using a user token to authenticate. For episodes in the playlist, if a user token is used, the country associated with it overrides this parameter. If an application token is used and no market is specified, episodes are considered unavailable and returned as None.
as_tracks (bool | Iterable[str]) – return types of items with track-like fields. If True, return all other types as tracks. If an iterable is passed, types contained are returned as tracks. Currently the only extra type is episode.
limit (int) – the number of items to return (1..100)
offset (int) – the index of the first item to return

Returns:

paging object containing playlist items, or raw dictionary if fields or as_tracks was specified

Return type:

PlaylistTrackPaging | dict

Spotify.playlist_add(playlist_id, uris, position=None)

Add items.

Required scope: playlist-modify-public

Optional scope: playlist-modify-private

Parameters:

playlist_id (str) – playlist ID
uris (list[str]) – list of URIs, max 100 without chunking
position (int | None) – index to insert the items in

Returns:

snapshot ID for the playlist

Return type:

str

Spotify.playlist_clear(playlist_id)

Remove all items.

Required scope: playlist-modify-public

Optional scope: playlist-modify-private

Parameters:: playlist_id (str) – playlist ID
Return type:: None

Spotify.playlist_remove(playlist_id, uris, snapshot_id=None)

Remove items by URI.

Required scope: playlist-modify-public

Optional scope: playlist-modify-private

Removes all occurrences of the specified items. Note that when chunked, snapshot_id is not updated between requests.

Parameters:

playlist_id (str) – playlist ID
uris (list[str]) – list of URIs, max 100 without chunking
snapshot_id (str | None) – snapshot ID for the playlist

Returns:

snapshot ID for the playlist

Return type:

str

Spotify.playlist_reorder(playlist_id, range_start, insert_before, range_length=1, snapshot_id=None)

Reorder items.

Required scope: playlist-modify-public

Optional scope: playlist-modify-private

Parameters:

playlist_id (str) – playlist ID
range_start (int) – position of the first item to be reordered
range_length (int) – number of items to be reordered
insert_before (int) – position where the items should be inserted
snapshot_id (str | None) – snapshot ID for the playlist

Returns:

snapshot ID for the playlist

Return type:

str

Spotify.playlist_replace(playlist_id, uris)

Replace all items.

Required scope: playlist-modify-public

Optional scope: playlist-modify-private

Parameters:

playlist_id (str) – playlist ID
uris (list[str]) – list of URIs, max 100

Return type:

None

Search API

Spotify.search(query, types=('track',), market=None, include_external=None, limit=20, offset=0)

Search for an item.

Required scope: none

Optional scope: none

Returns NotFound if limit+offset would be above 1000.

Parameters:

query (str) – search query
types (tuple) – resources to search for, tuple of strings containing artist, album, audiobook, track, playlist, show and/or episode
market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return
include_external (str | None) – if ‘audio’, response will include any externally hosted audio

Returns:

Paging objects containing the types of items searched for in the order that they were specified in ‘types’.

Return type:

tuple

Examples

tracks, = spotify.search('monty python')
artists, = spotify.search('sheeran', types=('artist',))
albums, tracks = spotify.search('piano', types=('album', 'track'))
spotify.search('gold album:boba artist:abba', types=('track',))
spotify.search('bob year:1980-2020', types=('show',))

Note

You can narrow down search results by specifying field filters (e.g. year range, genre). See the Search for an Item page of the official documentation for more information.

Show API

`Spotify.show`	Get information for a show.
`Spotify.show_episodes`	Get episodes of a show.
`Spotify.shows`	Get information for multiple shows.

Spotify.show(show_id, market=None)

Get information for a show.

Required scope: none

Optional scope: user-read-playback-position

The user-read-playback-position scope allows episode resume points to be returned.

Parameters:

show_id (str) – show ID
market (str | None) – an ISO 3166-1 alpha-2 country code. If a user token is used to authenticate, the country associated with it overrides this parameter. If an application token is used and no market is specified, the show is considered unavailable.

Return type:

FullShow

Spotify.show_episodes(show_id, market=None, limit=20, offset=0)

Get episodes of a show.

Required scope: none

Optional scope: none

Parameters:

show_id (str) – show ID
market (str | None) – an ISO 3166-1 alpha-2 country code. If a user token is used to authenticate, the country associated with it overrides this parameter. If an application token is used and no market is specified, the show is considered unavailable.
limit (int) – the number of items to return (1..50)
offset (int) – the index of the first item to return

Return type:

SimpleEpisodePaging

Spotify.shows(show_ids, market=None)

Get information for multiple shows.

Required scope: none

Optional scope: user-read-playback-position

The user-read-playback-position scope allows episode resume points to be returned.

Parameters:

show_ids (list[str]) – the show IDs, max 50 without chunking
market (str | None) – an ISO 3166-1 alpha-2 country code. If a user token is used to authenticate, the country associated with it overrides this parameter. If an application token is used and no market is specified, the show is considered unavailable.

Return type:

list[FullShow]

Track API

`Spotify.track`	Get information for a track.
`Spotify.track_audio_analysis`	Get a detailed audio analysis for a track.
`Spotify.track_audio_features`	Get audio feature information for a track.
`Spotify.tracks`	Get information for multiple tracks.
`Spotify.tracks_audio_features`	Get audio feature information for multiple tracks.

Spotify.track(track_id, market=None)

Get information for a track.

Required scope: none

Optional scope: none

Parameters:

track_id (str) – track ID
market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’

Return type:

FullTrack

Spotify.track_audio_analysis(track_id)

Get a detailed audio analysis for a track.

Required scope: none

Optional scope: none

Warning

This endpoint is unavailable to new third-party applications (#331)

The analysis describes the track’s structure and musical content, including rythm, pitch and timbre.

Parameters:: track_id (str) –
Return type:: AudioAnalysis

Spotify.track_audio_features(track_id)

Get audio feature information for a track.

Required scope: none

Optional scope: none

Warning

This endpoint is unavailable to new third-party applications (#331)

Parameters:: track_id (str) –
Return type:: AudioFeatures

Spotify.tracks(track_ids, market=None)

Get information for multiple tracks.

Required scope: none

Optional scope: none

Parameters:

track_ids (list[str]) – the track IDs, max 50 without chunking
market (str | None) – an ISO 3166-1 alpha-2 country code or ‘from_token’

Return type:

list[FullTrack]

Spotify.tracks_audio_features(track_ids)

Get audio feature information for multiple tracks.

Required scope: none

Optional scope: none

Warning

This endpoint is unavailable to new third-party applications (#331)

Feature information for a track may be None if not available.

Parameters:: track_ids (list[str]) – track IDs, max 100 without chunking
Return type:: list[AudioFeatures]

User API

`Spotify.current_user`	Get current user's profile.
`Spotify.user`	Get a user's profile.

Spotify.current_user()

Get current user’s profile.

Required scope: none

Optional scope: user-read-email user-read-private

The user-read-private scope allows the user’s country and product subscription level to be returned.

Return type:: PrivateUser

Spotify.user(user_id)

Get a user’s profile.

Required scope: none

Optional scope: none

Parameters:: user_id (str) – user ID
Return type:: PublicUser