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) – request sender

  • asynchronous (bool) – 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()

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) –

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

Union[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

Union[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) – 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) – 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) – list of album IDs, max 20 without chunking

  • market (str) – 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[Union[str, AlbumGroup]]) – album groups to include in the response

  • market (str) – 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

Get artists similar to an identified artist.

Required scope: none
Optional scope: none

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) – 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) – 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) – 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) – the audiobook IDs, max 50 without chunking

  • market (str) – 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) – an ISO 3166-1 alpha-2 country code

  • locale (str) – 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) – an ISO 3166-1 alpha-2 country code

  • locale (str) – 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
Parameters
  • category_id (str) – category ID

  • country (str) – 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
Parameters
  • country (str) – an ISO 3166-1 alpha-2 country code

  • locale (str) – 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) – 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) – 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

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) – list of seed artist IDs

  • genres (list) – list of seed genre names

  • track_ids (list) – list of seed track IDs

  • limit (int) – the number of items to return (1..100)

  • market (str) – 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) – 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) – the chapter IDs, max 50 without chunking

  • market (str) – 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) – 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) – the episode IDs, max 50 without chunking

  • market (str) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – list of show IDs, max 50 without chunking

  • market (str) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – a unix timestamp in milliseconds, must not be specified with ‘before’

  • before (int) – 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 (Union[str, RepeatState]) – track, context, or off

  • device_id (str) – 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) – 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) – 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) – 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 (Union[int, str]) – offset into context by index or track ID, only available when context is an album or playlist

  • position_ms (int) – initial position of first played track

  • device_id (str) – 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) – track IDs to start playing

  • offset (Union[int, str]) – offset into tracks by index or track ID

  • position_ms (int) – initial position of first played track

  • device_id (str) – 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) – 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_remove_indices

Remove items by position.

Spotify.playlist_remove_occurrences

Remove items by URI and position.

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) – which fields to return, see the Web API documentation for details

  • market (str) – 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 (Union[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

Union[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) – name of the playlist

  • public (bool) – is the playlist public

  • collaborative (bool) – is the playlist collaborative

  • description (str) – 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
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) – which fields to return, see the Web API documentation for details

  • market (str) – 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 (Union[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

Union[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) – list of URIs, max 100 without chunking

  • position (int) – 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) – list of URIs, max 100 without chunking

  • snapshot_id (str) – snapshot ID for the playlist

Returns

snapshot ID for the playlist

Return type

str

Spotify.playlist_remove_indices(playlist_id, indices, snapshot_id)

Remove items by position.

Required scope: playlist-modify-public
Optional scope: playlist-modify-private
Parameters
  • playlist_id (str) – playlist ID

  • indices (list) – a list of indices of tracks to remove

  • snapshot_id (str) – snapshot ID for the playlist

Returns

snapshot ID for the playlist

Return type

str

Spotify.playlist_remove_occurrences(playlist_id, refs, snapshot_id=None)

Remove items by URI and position.

Required scope: playlist-modify-public
Optional scope: playlist-modify-private
Parameters
  • playlist_id (str) – playlist ID

  • refs (List[Tuple[str, int]]) – a list of tuples containing the URI and index of items to remove

  • snapshot_id (str) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – the show IDs, max 50 without chunking

  • market (str) – 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) – 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

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
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) – the track IDs, max 50 without chunking

  • market (str) – 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

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

Parameters

track_ids (list) – 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