Welcome to Spotipy!¶

Spotipy cost a lightweight python library for the Spotify world wide web API. With Spotipy you bring full access to wholly of the music datum provide aside the Spotify platform .
wear you specify the SPOTIPY_CLIENT_ID and SPOTIPY_CLIENT_SECRET environment variable, here ’ s angstrom quick exercise of use Spotipy to number the name of all the album free aside the artist ‘ Birdy ’ :

 spell 
Reading: Welcome to Spotipy! — spotipy 2.0 documentation 
  spotipy
 from  spotipy.oauth2  import  SpotifyClientCredentials

 birdy_uri  =  'spotify : artist:2WX2uTcsvV5OnS0inACecP '
 spotify  =  spotipy. Spotify ( client_credentials_manager = SpotifyClientCredentials ( ) )

 result  =  spotify. artist_albums ( birdy_uri,  album_type = 'album ' )
 album  =  result [ 'items ' ]
 while  result [ 'next ' ] :
     resultant role  =  spotify. adjacent ( consequence )
     album. prolong ( consequence [ 'items ' ] )

 for  album  in  album :
     photographic print ( album [ 'name ' ] )

here ’ south another example express how to catch thirty second base sample and traverse art for the top ten track for lead zeppelin :

 spell  spotipy
 from  spotipy.oauth2  import  SpotifyClientCredentials

 lz_uri  =  'spotify : artist:36QJpDe2go2KgaRleHCDTp '

 spotify  =  spotipy. Spotify ( client_credentials_manager = SpotifyClientCredentials ( ) )
 result  =  spotify. artist_top_tracks ( lz_uri )

 for  racetrack  in  result [ 'tracks ' ] [ : ten ] :
     print ( 'track : '  +  path [ 'name ' ] )
     print ( 'audio : '  +  path [ 'preview_url ' ] )
     print ( 'cover artwork : '  +  track [ 'album ' ] [ 'images ' ] [ zero ] [ 'url ' ] )
     print ( )

ultimately, here ’ s associate in nursing exercise that will suffer the url for associate in nursing artist visualize give the artist ’ south name :

 significance  spotipy
 spell  sys
 from  spotipy.oauth2  import  SpotifyClientCredentials

 spotify  =  spotipy. Spotify ( auth_manager = SpotifyClientCredentials ( ) )

 if  len ( sys. argv )  >  one :
     name  =  ' '. join ( sys. argv [ one : ] )
 else :
     name  =  'Radiohead '

 result  =  spotify. search ( q = 'artist : '  +  name,  type = 'artist ' )
 item  =  consequence [ 'artists ' ] [ 'items ' ]
 if  len ( item )  >  zero :
     artist  =  item [ zero ]
     print ( artist [ 'name ' ],  artist [ 'images ' ] [ zero ] [ 'url ' ] )

Features¶

Spotipy support wholly of the feature of the Spotify web API include access to wholly end point, and support for user authorization. For details along the capability you be encourage to revue the Spotify world wide web API documentation .

Installation¶

install oregon upgrade Spotipy with :

 pip  install  spotipy  -- ascent

operating room you can suffer the source from github astatine hypertext transfer protocol : //github.com/plamere/spotipy

Getting Started¶

wholly method command drug user authorization. You bequeath motivation to register your app at My splashboard to induce the certificate necessary to brand authorize call ( vitamin a client idaho and node secret ) .
Spotipy back deuce mandate flow :

• The Authorization Code flow This method acting equal desirable for long-running application which the user log into once. information technology provide associate in nursing entree keepsake that buttocks equal review .
  note
  ask you to total adenine redirect URI to your application astatine My dashboard. meet redirect URI for more detail .
• The Client Credentials flow The method acting make information technology possible to authenticate your request to the Spotify vane API and to prevail angstrom eminent rate restrict than you would with the authorization code stream .

Authorization Code Flow¶

This stream be desirable for long-running application inch which the exploiter concede permission only once. information technology leave associate in nursing access token that can be fresh. Since the token commute involve send your secret key, perform this on vitamin a impregnable localization, like ampere backend service, and not from angstrom node such vitamin a adenine browser oregon from a mobile app .

Quick start¶

To support the Client Authorization Code Flow Spotipy provide ampere class SpotifyOAuth that can be secondhand to authenticate request comparable then :

 import  spotipy
 from  spotipy.oauth2  significance  SpotifyOAuth

 scope  =  `` user-library-read ''

 sp  =  spotipy. Spotify ( auth_manager = SpotifyOAuth ( telescope = oscilloscope ) )

 result  =  sp. current_user_saved_tracks ( )
 for  idx,  item  inch  count ( result [ 'items ' ] ) :
     path  =  item [ 'track ' ]
     print ( idx,  traverse [ 'artists ' ] [ zero ] [ 'name ' ],  `` – ``,  traverse [ 'name ' ] )

oregon if you exist loath to commemorate your app certificate indium your source code, you displace determined environment variable like sol ( manipulation SET rather of export on window ) :

 export  SPOTIPY_CLIENT_ID = 'your-spotify-client-id '
 export  SPOTIPY_CLIENT_SECRET = 'your-spotify-client-secret '
 export  SPOTIPY_REDIRECT_URI = 'your-app-redirect-url '

Scopes¶

see use scope for information approximately telescope .

Redirect URI¶

The Authorization Code Flow need you to add vitamin a redirect URI to your application astatine My dashboard ( voyage to your application and then [ edit setting ] ) .
The redirect_uri argument operating room SPOTIPY_REDIRECT_URI environment variable must match the redirect URI add to your application in your splashboard. The redirect URI can constitute any valid URI ( information technology do not need to be accessible ) such ampere http://example.com, http://localhost oregon http://127.0.0.1:9090 .

Client Credentials Flow¶

The node certificate flow exist use indiana server-to-server authentication. only end point that make not access user information can be access. The advantage hera indium comparison with request to the world wide web API make without associate in nursing access token, be that deoxyadenosine monophosphate eminent rate limit be put on .
a opposed to the authorization code flow, you bequeath not need to set SPOTIPY_REDIRECT_URI, which mean you will never be redirect to the sign indium page in your browser :

 export  SPOTIPY_CLIENT_ID = 'your-spotify-client-id '
 export  SPOTIPY_CLIENT_SECRET = 'your-spotify-client-secret '

To corroborate the Client Credentials Flow Spotipy provide adenine class SpotifyClientCredentials that can be secondhand to authenticate request like sol :

 meaning  spotipy
 from  spotipy.oauth2  import  SpotifyClientCredentials

 auth_manager  =  SpotifyClientCredentials ( )
 sp  =  spotipy. Spotify ( auth_manager = auth_manager )

 playlist  =  sp. user_playlists ( 'spotify ' )
 while  playlist :
     for  one,  playlist  in  count ( playlist [ 'items ' ] ) :
         print ( `` % 4d  % mho  % sulfur ``  %  ( one  +  one  +  playlist [ 'offset ' ],  playlist [ 'uri ' ],   playlist [ 'name ' ] ) )
     if  playlist [ 'next ' ] :
         playlist  =  sp. adjacent ( playlist )
     else :
         playlist  =  none

IDs URIs and URLs¶

Spotipy patronize vitamin a number of different idaho type :

• Spotify URI – The resource identifier that you can enter, for example, in
  the Spotify Desktop client’s search box to locate an artist, album, or
  track. Example: spotify : track:6rqhFgbbKwnb9MLmUQDhG6
• Spotify URL – An HTML link that opens a track, album, app, playlist or other
  Spotify resource in a Spotify client. Example:
  hypertext transfer protocol : //open.spotify.com/track/6rqhFgbbKwnb9MLmUQDhG6
• Spotify ID – A base-62 number that you can find at the end of the Spotify
  URI (see above) for an artist, track, album, etc. Example:
  6rqhFgbbKwnb9MLmUQDhG6

inch general, any Spotipy method acting that need associate in nursing artist, album, track operating room playlist id bequeath accept idaho indiana any of the above shape

Examples¶

there be many more case of how to use Spotipy in the model directory on Github

API Reference¶

client Module¶

a simpleton and thin python library for the Spotify vane API

class spotipy.client.Spotify (auth=None, requests_session=True, client_credentials_manager=None, oauth_manager=None, auth_manager=None, proxies=None, requests_timeout=5, status_forcelist=None, retries=3, status_retries=3, backoff_factor=0.3, language=None )¶

basis : object
exercise use :

 consequence  spotipy

 urn  =  'spotify : artist:3jOstUTkEu2JkjvRdBA5Gu '
 sp  =  spotipy. 
Read more : ‎Spotify - Music and Podcasts 
 Spotify ( )

 artist  =  sp. artist ( urn )
 print ( artist )

 user  =  sp. user ( 'plamere ' )
 print ( user )

__init__ (auth=None, requests_session=True, client_credentials_manager=None, oauth_manager=None, auth_manager=None, proxies=None, requests_timeout=5, status_forcelist=None, retries=3, status_retries=3, backoff_factor=0.3, language=None )¶

create vitamin a Spotify API customer .

Parameters:

auth – An authorization token (optional) requests_session – A Requests session object or a truthy value to create one. A falsy value disables sessions. It should generally be a good idea to keep sessions enabled for performance reasons (connection pooling). client_credentials_manager – SpotifyClientCredentials object oauth_manager – SpotifyOAuth object auth_manager – SpotifyOauth, SpotifyClientCredentials, or SpotifyImplicitGrant object proxies – Definition of proxies (optional). See Requests doc https://2.python-requests.org/en/master/user/advanced/#proxies requests_timeout – Tell Requests to stop waiting for a response after a given number of seconds status_forcelist – Tell requests what type of status codes retries should occur on retries – Total number of retries to allow status_retries – Number of times to retry on bad status codes backoff_factor – A backoff factor to apply between attempts after the second try See urllib3 https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html language – The language parameter advertises what language the user prefers to see. See ISO-639 language code: https://www.loc.gov/standards/iso639-2/php/code_list.php

add_to_queue (uri, device_id=None )¶

attention deficit disorder ampere song to the end of adenine exploiter ’ second queue
If device a be presently play music and you attempt to attention deficit disorder to the queue and pass in the idaho for device boron, you bequeath get ampere ‘ actor command fail : limitation rape ’ error one therefore reccomend forget device_id equally none so that the active device cost target

Parameters:	uri – song uri, id, or url device_id – the id of a Spotify device. If None, then the active device is used.

album (album_id )¶

rejoinder angstrom single album give the album ’ randomness idaho, URIs oregon url

Parameters:

• album_id – the album ID, URI or URL

album_tracks (album_id, limit=50, offset=0, market=None )¶

get Spotify catalogue information about associate in nursing album ’ randomness track

Parameters:

• album_id – the album ID, URI or URL
• limit – the number of items to return
• offset – the index of the first item to return
• market – an ISO 3166-1 alpha-2 country code.

albums (albums )¶

return adenine list of album give the album id, URIs, oregon url

Parameters:

• albums – a list of album IDs, URIs or URLs

artist (artist_id )¶

return a single artist give the artist ’ mho id, URI oregon url

Parameters:

• artist_id – an artist ID, URI or URL

artist_albums (artist_id, album_type=None, country=None, limit=20, offset=0 )¶

catch Spotify catalogue information about associate in nursing artist ’ south album

Parameters:

• artist_id – the artist ID, URI or URL
• album_type – ‘album’, ‘single’, ‘appears_on’, ‘compilation’
• country – limit the response to one particular country.
• limit – the number of albums to return
• offset – the index of the first album to return

artist_related_artists (artist_id )¶

get Spotify catalog information about artist like to associate in nursing identified artist. similarity be free-base along psychoanalysis of the Spotify residential district ’ second listening history .

Parameters:

• artist_id – the artist ID, URI or URL

artist_top_tracks (artist_id, country=’US’ )¶

get Spotify catalog information about associate in nursing artist ’ sulfur top ten track by country .

Parameters:

• artist_id – the artist ID, URI or URL
• country – limit the response to one particular country.

artists (artists )¶

reelect adenine list of artist give the artist id, URIs, operating room url

Parameters:

• artists – a list of artist IDs, URIs or URLs

audio_analysis (track_id )¶

draw audio analysis for angstrom cut based upon information technology Spotify id parameter :

• track_id – a track URI, URL or ID

audio_features (tracks=[] )¶

bring audio sport for one operating room multiple chase establish upon their Spotify idaho parameter :

• tracks – a list of track URIs, URLs or IDs, maximum: 100 ids

auth_manager¶

categories (country=None, locale=None, limit=20, offset=0 )¶

contract deoxyadenosine monophosphate list of category

Parameters:

• country – An ISO 3166-1 alpha-2 country code.
• locale – The desired language, consisting of an ISO 639
  language code and an ISO 3166-1 alpha-2 country code, joined
  by an underscore.
• limit – The maximum number of items to return. Default: 20.
  Minimum: 1. Maximum: 50
• offset – The index of the first item to return. Default: 0
  (the first object). Use with limit to get the next set of
  items.

category (category_id, country=None, locale=None )¶

get down information about a class

Parameters:

• category_id – The Spotify category ID for the category.
• country – An ISO 3166-1 alpha-2 country code.
• locale – The desired language, consisting of an ISO 639
  language code and an ISO 3166-1 alpha-2 country code, joined
  by an underscore.

category_playlists (category_id=None, country=None, limit=20, offset=0 )¶

catch a tilt of playlist for angstrom particular Spotify category

Parameters:

• category_id – The Spotify category ID for the category.
• country – An ISO 3166-1 alpha-2 country code.
• limit – The maximum number of items to return. Default: 20.
  Minimum: 1. Maximum: 50
• offset – The index of the first item to return. Default: 0
  (the first object). Use with limit to get the next set of
  items.

country_codes = [‘AD’, ‘AR’, ‘AU’, ‘AT’, ‘BE’, ‘BO’, ‘BR’, ‘BG’, ‘CA’, ‘CL’, ‘CO’, ‘CR’, ‘CY’, ‘CZ’, ‘DK’, ‘DO’, ‘EC’, ‘SV’, ‘EE’, ‘FI’, ‘FR’, ‘DE’, ‘GR’, ‘GT’, ‘HN’, ‘HK’, ‘HU’, ‘IS’, ‘ID’, ‘IE’, ‘IT’, ‘JP’, ‘LV’, ‘LI’, ‘LT’, ‘LU’, ‘MY’, ‘MT’, ‘MX’, ‘MC’, ‘NL’, ‘NZ’, ‘NI’, ‘NO’, ‘PA’, ‘PY’, ‘PE’, ‘PH’, ‘PL’, ‘PT’, ‘SG’, ‘ES’, ‘SK’, ‘SE’, ‘CH’, ‘TW’, ‘TR’, ‘GB’, ‘US’, ‘UY’]¶

current_playback (market=None, additional_types=None )¶

get information about user ’ randomness current playback .

Parameters:

• market – an ISO 3166-1 alpha-2 country code.
• additional_types – episode to get podcast track information

current_user ( )¶

get detail profile information about the stream drug user. associate in nursing alias for the ‘ maine ’ method acting .

current_user_follow_playlist (playlist_id )¶

add the current authenticate drug user a vitamin a follower of a playlist .

Parameters:

• playlist_id – the id of the playlist

current_user_followed_artists (limit=20, after=None )¶

get ampere list of the artist play along aside the current authorize user

Parameters:

• limit – the number of artists to return

• after – the last artist ID retrieved from the previous

  request

current_user_following_artists (ids=None )¶

check if the current user exist follow certain artist
fall number of booleans respective to idaho

Parameters:

• ids – a list of artist URIs, URLs or IDs

current_user_following_users (ids=None )¶

check if the current exploiter embody postdate certain artist
return list of booleans respective to id

Parameters:

• ids – a list of user URIs, URLs or IDs

current_user_playing_track ( )¶

experience information about the current drug user presently play track .

current_user_playlists (limit=50, offset=0 )¶

suffer current user playlist without command acquiring his profile parameter :

• limit – the number of items to return
• offset – the index of the first item to return

current_user_recently_played (limit=50, after=None, before=None )¶

bring the current exploiter ’ south recently play chase

Parameters:

• limit – the number of entities to return

• after – unix timestamp in milliseconds. Returns all items

  after (but not including) this cursor position.
  Cannot be used if before is specified.

• before – unix timestamp in milliseconds. Returns all items

  before (but not including) this cursor position.
  Cannot be used if after is specified

current_user_saved_albums (limit=20, offset=0 )¶

become a list of the album deliver indium the current authoritative drug user ’ mho “ Your music ” library

Parameters:

• limit – the number of albums to return
• offset – the index of the first album to return

current_user_saved_albums_add (albums=[] )¶

add one oregon more album to the stream user ’ sulfur “ Your music ” library. parameter :

• albums – a list of album URIs, URLs or IDs

current_user_saved_albums_contains (albums=[] )¶

discipline if one operating room more album be already keep open in the current Spotify drug user ’ s “ Your music ” library .

Parameters:

• albums – a list of album URIs, URLs or IDs

current_user_saved_albums_delete (albums=[] )¶

remove one operating room more album from the current drug user ’ sulfur “ Your music ” library .

Parameters:

• albums – a list of album URIs, URLs or IDs

current_user_saved_shows (limit=50, offset=0 )¶

catch angstrom number of the show deliver inch the current authorize drug user ’ second “ Your music ” library

Parameters:

• limit – the number of shows to return
• offset – the index of the first show to return

current_user_saved_shows_add (shows=[] )¶

add one oregon more album to the current user ’ second “ Your music ” library. argument :

• shows – a list of show URIs, URLs or IDs

current_user_saved_shows_contains (shows=[] )¶

discipline if one operating room more show cost already save in the current Spotify exploiter ’ sulfur “ Your music ” library .

Parameters:

• shows – a list of show URIs, URLs or IDs

current_user_saved_shows_delete (shows=[] )¶

get rid of one oregon more usher from the current exploiter ’ second “ Your music ” library .

Parameters:

• shows – a list of show URIs, URLs or IDs

current_user_saved_tracks (limit=20, offset=0 )¶

get a list of the lead spare inch the current authorize exploiter ’ sulfur “ Your music ” library

Parameters:

• limit – the number of tracks to return
• offset – the index of the first track to return

current_user_saved_tracks_add (tracks=None )¶

attention deficit disorder one oregon more chase to the current drug user ’ sulfur “ Your music ” library .

Parameters:

• tracks – a list of track URIs, URLs or IDs

current_user_saved_tracks_contains (tracks=None )¶

check if one operating room more track be already salvage indiana the current Spotify exploiter ’ second “ Your music ” library .

Parameters:

• tracks – a list of track URIs, URLs or IDs

current_user_saved_tracks_delete (tracks=None )¶

remove one operating room more track from the current user ’ s “ Your music ” library .

Parameters:

• tracks – a list of track URIs, URLs or IDs

current_user_top_artists (limit=20, offset=0, time_range=’medium_term’ )¶

catch the current drug user ’ sulfur top artist

Parameters:

• limit – the number of entities to return
• offset – the index of the first entity to return
• time_range – Over what time frame are the affinities computed
  Valid-values: short_term, medium_term, long_term

current_user_top_tracks (limit=20, offset=0, time_range=’medium_term’ )¶

have the current exploiter ’ randomness top traverse

Parameters:

• limit – the number of entities to return
• offset – the index of the first entity to return
• time_range – Over what time frame are the affinities computed
  Valid-values: short_term, medium_term, long_term

current_user_unfollow_playlist (playlist_id )¶

Unfollows ( delete ) adenine playlist for the current attested drug user

Parameters:

• name – the name of the playlist

currently_playing (market=None, additional_types=None )¶

get exploiter ’ s presently play track .

Parameters:

• market – an ISO 3166-1 alpha-2 country code.
• additional_types – episode to get podcast track information

default_retry_codes = (429, 500, 502, 503, 504)¶

devices ( )¶

get angstrom list of drug user ’ randomness available device .

episode (episode_id, market=None )¶

fall adenine single sequence give the episode ’ south idaho, URIs oregon url

Parameters:

• episode_id – the episode ID, URI or URL

• market – an ISO 3166-1 alpha-2 country code.

  The episode must be available in the given market.
  If user-based authorization is in use, the user’s country
  takes precedence. If neither market nor user country are
  provided, the content is considered unavailable for the client.

episodes (episodes, market=None )¶

return ampere number of episode give the episode id, URIs, operating room url

Parameters:

• episodes – a list of episode IDs, URIs or URLs

• market – an ISO 3166-1 alpha-2 country code.

  Only episodes available in the given market will be returned.
  If user-based authorization is in use, the user’s country
  takes precedence. If neither market nor user country are
  provided, the content is considered unavailable for the client.

featured_playlists (locale=None, country=None, timestamp=None, limit=20, offset=0 )¶

get down adenine number of Spotify have playlist

Parameters:

• locale – 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.
• country – An ISO 3166-1 alpha-2 country code.
• timestamp – A timestamp in ISO 8601 format:
  yyyy-MM-ddTHH:mm:ss. Use this parameter to specify the user’s
  local time to get results tailored for that specific date and
  time in the day
• limit – The maximum number of items to return. Default: 20.
  Minimum: 1. Maximum: 50
• offset – The index of the first item to return. Default: 0
  (the first object). Use with limit to get the next set of
  items.

max_retries = 3¶

me ( )¶

get detail profile information about the stream drug user. associate in nursing alias for the ‘ current_user ’ method .

new_releases (country=None, limit=20, offset=0 )¶

catch ampere list of new album let go of sport indiana Spotify

Parameters:

• country – An ISO 3166-1 alpha-2 country code.
• limit – The maximum number of items to return. Default: 20.
  Minimum: 1. Maximum: 50
• offset – The index of the first item to return. Default: 0
  (the first object). Use with limit to get the next set of
  items.

next (result )¶

return the following leave give ampere page resultant role

Parameters:

• result – a previously returned paged result

next_track (device_id=None )¶

cut drug user ’ second playback to following track .

Parameters:

• device_id – device target for playback

pause_playback (device_id=None )¶

pause exploiter ’ mho playback .

Parameters:

• device_id – device target for playback

playlist (playlist_id, fields=None, market=None, additional_types=(‘track’, ) )¶

catch playlist by id .

Parameters:

• playlist – the id of the playlist
• fields – which fields to return

• market – An ISO 3166-1 alpha-2 country code or the

  string from_token.

• additional_types – list of item types to return.

  valid types are: track and episode

playlist_add_items (playlist_id, items, position=None )¶

lend tracks/episodes to angstrom playlist

Parameters:

• playlist_id – the id of the playlist
• items – a list of track/episode URIs, URLs or IDs
• position – the position to add the tracks

playlist_change_details (playlist_id, name=None, public=None, collaborative=None, description=None )¶

change deoxyadenosine monophosphate playlist ’ randomness appoint and/or public/private country

Parameters:

• playlist_id – the id of the playlist
• name – optional name of the playlist
• public – optional is the playlist public
• collaborative – optional is the playlist collaborative
• description – optional description of the playlist

playlist_cover_image (playlist_id )¶

get cover of angstrom playlist .

Parameters:

• playlist_id – the id of the playlist

playlist_is_following (playlist_id, user_ids )¶

check to meet if the collapse drug user cost pursue the establish playlist

Parameters:

• playlist_id – the id of the playlist

• user_ids – the ids of the users that you want to check to see

  if they follow the playlist. Maximum: 5 ids.

playlist_items (playlist_id, fields=None, limit=100, offset=0, market=None, additional_types=(‘track’, ‘episode’) )¶

grow fully detail of the track and episode of a playlist .

Parameters:

• playlist_id – the id of the playlist
• fields – which fields to return
• limit – the maximum number of tracks to return
• offset – the index of the first track to return
• market – an ISO 3166-1 alpha-2 country code.

• additional_types – list of item types to return.

  valid types are: track and episode

playlist_remove_all_occurrences_of_items (playlist_id, items, snapshot_id=None )¶

remove all happening of the hold traverse from the give playlist

Parameters:

• playlist_id – the id of the playlist
• items – list of track/episode ids to remove from the playlist
• snapshot_id – optional id of the playlist snapshot

playlist_remove_specific_occurrences_of_items (playlist_id, items, snapshot_id=None )¶

remove all occurrence of the grant track from the give playlist

Parameters:

• playlist_id – the id of the playlist

• items – an array of objects containing Spotify URIs of the

  tracks/episodes to get rid of with their current position indiana the playlist. For example :

  [ { “ uri ” : ” 4iV5W9uYEdYUVa79Axb7Rh ”, “ position ” : [ two ] }, { “ uri ” : ” 1301WleyT98MSxVHPZCA6M ”, “ position ” : [ seven ] } ]

• snapshot_id – optional idaho of the playlist snapshot

playlist_reorder_items (playlist_id, range_start, insert_before, range_length=1, snapshot_id=None )¶

reorder track inch deoxyadenosine monophosphate playlist

Parameters:

• playlist_id – the id of the playlist
• range_start – the position of the first track to be reordered

• range_length – optional the number of tracks to be reordered

  (default: 1)

• insert_before – the position where the tracks should be

  inserted

• snapshot_id – optional playlist’s snapshot ID

playlist_replace_items (playlist_id, items )¶

supplant all tracks/episodes in a playlist

Parameters:

• playlist_id – the id of the playlist
• items – list of track/episode ids to comprise playlist

playlist_tracks (playlist_id, fields=None, limit=100, offset=0, market=None, additional_types=(‘track’, ) )¶

get wide detail of the cut of adenine playlist .

Parameters:

• playlist_id – the id of the playlist
• fields – which fields to return
• limit – the maximum number of tracks to return
• offset – the index of the first track to return
• market – an ISO 3166-1 alpha-2 country code.

• additional_types – list of item types to return.

  valid types are: track and episode

playlist_upload_cover_image (playlist_id, image_b64 )¶

substitute the effigy use to constitute ampere specific playlist

Parameters:

• playlist_id – the id of the playlist

• image_b64 – image data as a Base64 encoded JPEG image string

  (maximum payload size is 256 KB)

previous (result )¶

retort the former result give adenine foliate resultant role

Parameters:

• result – a previously returned paged result

previous_track (device_id=None )¶

omission exploiter ’ s playback to previous chase .

Parameters:

• device_id – device target for playback

recommendation_genre_seeds ( )¶

catch a tilt of genre available for the recommendation serve .

recommendations (seed_artists=None, seed_genres=None, seed_tracks=None, limit=20, country=None, **kwargs )¶

get ampere list of recommend racetrack for one to basketball team seed. ( at least one of seed_artists, seed_tracks and seed_genres be needed )

Parameters:

• seed_artists – a list of artist IDs, URIs or URLs
• seed_tracks – a list of track IDs, URIs or URLs

• seed_genres – a list of genre names. Available genres for

  recommendations can be found by calling
  recommendation_genre_seeds

• country – An ISO 3166-1 alpha-2 country code. If provided,

  all results will be playable in this country.

• limit – The maximum number of items to return. Default: 20.

  Minimum: 1. Maximum: 100

• min/max/target_ – For the tuneable track

  attributes listed in the documentation, these values
  provide filters and targeting on results.

repeat (state, device_id=None )¶

determine repeat mood for playback .

Parameters:

• state – track, context, or off
• device_id – device target for playback

search (q, limit=10, offset=0, type=’track’, market=None )¶

search for associate in nursing item

Parameters:

• q – the search query (see how to write a query in the

  official documentation https://developer.spotify.com/documentation/web-api/reference/search/search/) # noqa

• limit – the number of items to return (min = 1, default = 10, max = 50)
• offset – the index of the first item to return

• type – the type of item to return. One of ‘artist’, ‘album’,

  ‘track’, ‘playlist’, ‘show’, or ‘episode’

• market – An ISO 3166-1 alpha-2 country code or the string

  from_token.

search_markets (q, limit=10, offset=0, type=’track’, markets=None, total=None )¶

( experimental ) search multiple marketplace for associate in nursing item

Parameters:

• q – the search query (see how to write a query in the

  official documentation https://developer.spotify.com/documentation/web-api/reference/search/search/) # noqa

• limit – the number of items to return (min = 1, default = 10, max = 50). If a search is to be done on multiple

  markets, then this limit is applied to each market. (e.g. search US, CA, MX each with a limit of 10).

• offset – the index of the first item to return

• type – the type’s of item’s to return. One or more of ‘artist’, ‘album’,

  ‘track’, ‘playlist’, ‘show’, or ‘episode’. If multiple types are desired, pass in a comma separated list.

• markets – A list of ISO 3166-1 alpha-2 country codes. Search all country markets by default.

• total – the total number of results to return if multiple markets are supplied in the search.

  If multiple types are specified, this only applies to the first type.

seek_track (position_ms, device_id=None )¶

search to military position in stream cut .

Parameters:

• position_ms – position in milliseconds to seek to
• device_id – device target for playback

set_auth (auth )¶

show (show_id, market=None )¶

return a single express give the show ’ second idaho, URIs oregon url

Parameters:

• show_id – the show ID, URI or URL

• market – an ISO 3166-1 alpha-2 country code.

  The show must be available in the given market.
  If user-based authorization is in use, the user’s country
  takes precedence. If neither market nor user country are
  provided, the content is considered unavailable for the client.

show_episodes (show_id, limit=50, offset=0, market=None )¶

get Spotify catalogue data about deoxyadenosine monophosphate appearance ’ randomness episode

Parameters:

• show_id – the show ID, URI or URL
• limit – the number of items to return
• offset – the index of the first item to return

• market – an ISO 3166-1 alpha-2 country code.

  Only episodes available in the given market will be returned.
  If user-based authorization is in use, the user’s country
  takes precedence. If neither market nor user country are
  provided, the content is considered unavailable for the client.

shows (shows, market=None )¶

return deoxyadenosine monophosphate list of show give the testify id, URIs, oregon url

Parameters:

• shows – a list of show IDs, URIs or URLs

• market – an ISO 3166-1 alpha-2 country code.

  Only shows available in the given market will be returned.
  If user-based authorization is in use, the user’s country
  takes precedence. If neither market nor user country are
  provided, the content is considered unavailable for the client.

shuffle (state, device_id=None )¶

toggle playback shuffle .

Parameters:

• state – true or false
• device_id – device target for playback

start_playback (device_id=None, context_uri=None, uris=None, offset=None, position_ms=None )¶

start oregon sketch drug user ’ sulfur playback .
leave vitamin a context_uri to startle playback operating room a album, artist, operating room playlist .
provide ampere uris list to start playback of one operating room more track .
provide outgrowth a { “ put ” : } or {“uri”: “”}
to start playback at a particular offset.

Parameters:

• device_id – device target for playback
• context_uri – spotify context uri to play
• uris – spotify track uris
• offset – offset into context by index or track

• position_ms – (optional) indicates from what position to start playback.

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

track (track_id )¶

return a one track yield the track ’ randomness id, URI oregon url

Parameters:

• track_id – a spotify URI, URL or ID

tracks (tracks, market=None )¶

reelect angstrom number of track give vitamin a list of traverse idaho, URIs, operating room url

Parameters:

• tracks – a list of spotify URIs, URLs or IDs. Maximum: 50 IDs.
• market – an ISO 3166-1 alpha-2 country code.

transfer_playback (device_id, force_play=True )¶

transfer playback to another device. note that the API accept a list of device idaho, merely alone actually accompaniment one .

Parameters:

• device_id – transfer playback to this device

• force_play – true: after transfer, play. false:

  keep current state.

user (user )¶

experience basic visibility information approximately a Spotify user

Parameters:

• user – the id of the usr

user_follow_artists (ids=[] )¶

succeed one oregon more artist parameter :

• ids – a list of artist IDs

user_follow_users (ids=[] )¶

take after one oregon more drug user parameter :

• ids – a list of user IDs

user_playlist (user, playlist_id=None, fields=None, market=None )¶

user_playlist_add_tracks (user, playlist_id, tracks, position=None )¶

user_playlist_change_details (user, playlist_id, name=None, public=None, collaborative=None, description=None )¶

user_playlist_create (user, name, public=True, collaborative=False, description=” )¶

make deoxyadenosine monophosphate playlist for adenine drug user

Parameters:

• user – the id of the user
• name – the name of the playlist
• public – is the created playlist public
• collaborative – is the created playlist collaborative
• description – the description of the playlist

user_playlist_follow_playlist (playlist_owner_id, playlist_id )¶

add the current authenticate drug user adenine a follower of vitamin a playlist .

Parameters:

• playlist_owner_id – the user id of the playlist owner
• playlist_id – the id of the playlist

user_playlist_is_following (playlist_owner_id, playlist_id, user_ids )¶

check to visualize if the give drug user embody pursue the give playlist

Parameters:

• playlist_owner_id – the user id of the playlist owner
• playlist_id – the id of the playlist

• user_ids – the ids of the users that you want to check to see

  if they follow the playlist. Maximum: 5 ids.

user_playlist_remove_all_occurrences_of_tracks (user, playlist_id, tracks, snapshot_id=None )¶

murder all occurrence of the give path from the give playlist

Parameters:

• user – the id of the user
• playlist_id – the id of the playlist
• tracks – the list of track ids to remove from the playlist
• snapshot_id – optional id of the playlist snapshot

user_playlist_remove_specific_occurrences_of_tracks (user, playlist_id, tracks, snapshot_id=None )¶

remove wholly happening of the give track from the give playlist

Parameters:

• user – the id of the exploiter
• playlist_id – the id of the playlist

• tracks – an array of objects containing Spotify URIs of the

  cut to remove with their current situation indium the playlist. For example :

  [ { “ uri ” : ” 4iV5W9uYEdYUVa79Axb7Rh ”, “ position ” : [ two ] }, { “ uri ” : ” 1301WleyT98MSxVHPZCA6M ”, “ placement ” : [ seven ] } ]

• snapshot_id – optional id of the playlist snapshot

user_playlist_reorder_tracks (user, playlist_id, range_start, insert_before, range_length=1, snapshot_id=None )¶

reorder traverse in a playlist

Parameters:

• user – the id of the user
• playlist_id – the id of the playlist
• range_start – the position of the first track to be reordered

• range_length – optional the number of tracks to be reordered

  (default: 1)

• insert_before – the position where the tracks should be

  inserted

• snapshot_id – optional playlist’s snapshot ID

user_playlist_replace_tracks (user, playlist_id, tracks )¶

supplant all path in adenine playlist

Parameters:

• user – the id of the user
• playlist_id – the id of the playlist
• tracks – the list of track ids to add to the playlist

user_playlist_tracks (user=None, playlist_id=None, fields=None, limit=100, offset=0, market=None )¶

user_playlist_unfollow (user, playlist_id )¶

Unfollows ( erase ) vitamin a playlist for adenine exploiter

Parameters:

• user – the id of the user
• name – the name of the playlist

user_playlists (user, limit=50, offset=0 )¶

experience playlist of adenine exploiter

Parameters:

• user – the id of the usr
• limit – the number of items to return
• offset – the index of the first item to return

user_unfollow_artists (ids=[] )¶

Unfollow one operating room more artist parameter :

• ids – a list of artist IDs

user_unfollow_users (ids=[] )¶

Unfollow matchless oregon more exploiter argument :

• ids – a list of user IDs

volume (volume_percent, device_id=None )¶

set playback volume .

Parameters:

• volume_percent – volume between 0 and 100
• device_id – device target for playback

exception spotipy.client.SpotifyException (http_status, code, msg, reason=None, headers=None )¶

al-qaeda : exceptions.Exception

__init__ (http_status, code, msg, reason=None, headers=None )¶

x.__init__ ( … ) initialize ten ; see assistant ( type ( x ) ) for signature

oauth2 Module¶

spotipy.oauth2.is_token_expired (token_info )¶

class spotipy.oauth2.SpotifyClientCredentials (client_id=None, client_secret=None, proxies=None, requests_session=True, requests_timeout=None )¶

nucleotide : spotipy.oauth2.SpotifyAuthBase

OAUTH_TOKEN_URL = ‘https://accounts.spotify.com/api/token’¶

__init__ (client_id=None, client_secret=None, proxies=None, requests_session=True, requests_timeout=None )¶

You can either provide deoxyadenosine monophosphate client_id and client_secret to the builder oregon hardening SPOTIPY_CLIENT_ID and SPOTIPY_CLIENT_SECRET environment variable

get_access_token (as_dict=True )¶

If ampere valid entree token be indiana memory, return information technology Else feches angstrom new token and recurrence information technology

parameter : – as_dict – adenine boolean indicate if refund the access token

deoxyadenosine monophosphate vitamin a token_info dictionary, otherwise information technology volition be return ampere adenine string .

is_token_expired (token_info )¶

class spotipy.oauth2.SpotifyOAuth (client_id=None, client_secret=None, redirect_uri=None, state=None, scope=None, cache_path=None, username=None, proxies=None, show_dialog=False, requests_session=True, requests_timeout=None, open_browser=True )¶

base : spotipy.oauth2.SpotifyAuthBase
enforce authorization code menstruate for Spotify ’ randomness OAuth implementation .

OAUTH_AUTHORIZE_URL = ‘https://accounts.spotify.com/authorize’¶

OAUTH_TOKEN_URL = ‘https://accounts.spotify.com/api/token’¶

__init__ (client_id=None, client_secret=None, redirect_uri=None, state=None, scope=None, cache_path=None, username=None, proxies=None, show_dialog=False, requests_session=True, requests_timeout=None, open_browser=True )¶

make ampere SpotifyOAuth object

Parameters:

• client_id: Must be supplied or set as environment variable
• client_secret: Must be supplied or set as environment variable
• redirect_uri: Must be supplied or set as environment variable
• state: May be supplied, no verification is performed
• scope: May be supplied, intuitively converted to proper format

• cache_path: May be supplied, will otherwise be generated

  (takes precedence over username)

• username: May be supplied or set as environment variable

  (will set cache_path to .cache-{username})

• proxies: Proxy for the requests library to route through
• show_dialog: Interpreted as boolean

• requests_timeout: Tell Requests to stop waiting for a response after a given number

  of seconds

• open_browser: Whether or not the web browser should be opened to authorize a user

get_access_token (code=None, as_dict=True, check_cache=True )¶

catch the access token for the app given the code

Parameters:

• code – the response code

• as_dict – a boolean indicating if returning the access token

  as a token_info dictionary, otherwise it will be returned
  as a string.

get_auth_response (open_browser=None )¶

get_authorization_code (response=None )¶

get_authorize_url (state=None )¶

perplex the url to use to authorize this app

get_cached_token ( )¶

induce a hoard auth token

is_token_expired (token_info )¶

static parse_auth_response_url (url )¶

parse_response_code (url )¶

parse the reaction code in the give reply url

Parameters:

• url – the response url

refresh_access_token (refresh_token )¶

exception spotipy.oauth2.SpotifyOauthError (message, error=None, error_description=None, *args, **kwargs )¶

basis : exceptions.Exception
error during Auth code operating room implicit grant flow

__init__ (message, error=None, error_description=None, *args, **kwargs )¶

x.__init__ ( … ) format adam ; see help ( type ( ten ) ) for signature

exception spotipy.oauth2.SpotifyStateError (local_state=None, remote_state=None, message=None, error=None, error_description=None, *args, **kwargs )¶

base : spotipy.oauth2.SpotifyOauthError
The submit send and state recieved be unlike

__init__ (local_state=None, remote_state=None, message=None, error=None, error_description=None, *args, **kwargs )¶

x.__init__ ( … ) format ten ; see help ( type ( ten ) ) for key signature

class spotipy.oauth2.SpotifyImplicitGrant (client_id=None, redirect_uri=None, state=None, scope=None, cache_path=None, username=None, show_dialog=False )¶

base : spotipy.oauth2.SpotifyAuthBase
implement implicit award flow for client apps
This auth director enable drug user and non-user end point with entirely ampere client secret, redirect uri, and username. The drug user will need to copy and glue adenine URI from the browser every hour .
The OAuth standard no longer recommend the implicit grant menstruation for client-side code. Spotify receive follow through the OAuth-suggested PKCE extension that absent the indigence for a customer secret indiana the authentication code stream. use the SpotifyPKCE auth coach alternatively of SpotifyImplicitGrant .
SpotifyPKCE contain all of the functionality of SpotifyImplicitGrant, summation automatic response retrieval and refreshable keepsake. only deoxyadenosine monophosphate few replacement indigence to beryllium produce :

• get_auth_response()[‘access_token’] ->
  get_access_token(get_authorization_code())
• get_auth_response() ->
  get_access_token(get_authorization_code()); get_cached_token()
• parse_response_token(url)[‘access_token’] ->
  get_access_token(parse_response_code(url))
• parse_response_token(url) ->
  get_access_token(parse_response_code(url)); get_cached_token()

The security concern in the Implict grant flow be that the token be return indium the url and can be intercept through the browser. vitamin a request with associate in nursing mandate code and proof of lineage could not be easily intercept without adenine compromise network .

OAUTH_AUTHORIZE_URL = ‘https://accounts.spotify.com/authorize’¶

__init__ (client_id=None, redirect_uri=None, state=None, scope=None, cache_path=None, username=None, show_dialog=False )¶

create Auth director use the implicit grant flow
See help(SpotifyImplictGrant) for full Security Warning

• client_id: Must be supplied or set as environment variable
• redirect_uri: Must be supplied or set as environment variable
• state: May be supplied, no verification is performed
• scope: May be supplied, intuitively converted to proper format

• cache_path: May be supplied, will otherwise be generated

  (takes precedence over username)

• username: May be supplied or set as environment variable

  (will set cache_path to .cache-{username})

• show_dialog: Interpreted as boolean

get_access_token (state=None, response=None, check_cache=True )¶

catch Auth nominal from hoard ( prefer ) oregon user interaction

• state: May be given, overrides (without changing) self.state
• response: URI with token, can break expiration checks
• check_cache: Interpreted as boolean

get_auth_response (state=None )¶

catch a newfangled auth token with user interaction

get_authorize_url (state=None )¶

bring the url to function to authorize this app

get_cached_token ( )¶

get angstrom hoard auth nominal

is_token_expired (token_info )¶

static parse_auth_response_url (url )¶

parse_response_token (url, state=None )¶

parse the reaction code in the give response url

class spotipy.oauth2.SpotifyPKCE (client_id=None, redirect_uri=None, state=None, scope=None, cache_path=None, username=None, proxies=None, requests_timeout=None, requests_session=True, open_browser=True )¶

base : spotipy.oauth2.SpotifyAuthBase
follow through PKCE authority flow for node apps
This auth coach enable drug user and non-user end point with entirely angstrom customer privy, redirect uri, and username. When the app request associate in nursing associate in nursing access token for the first gear time, the exploiter be motivate to authorize the new customer app. subsequently authorize the app, the client app be then give both entree and refresh token. This be the favored way of authorize ampere mobile/desktop customer .

OAUTH_AUTHORIZE_URL = ‘https://accounts.spotify.com/authorize’¶

OAUTH_TOKEN_URL = ‘https://accounts.spotify.com/api/token’¶

__init__ (client_id=None, redirect_uri=None, state=None, scope=None, cache_path=None, username=None, proxies=None, requests_timeout=None, requests_session=True, open_browser=True )¶

make Auth coach with the PKCE Auth stream .

Parameters:

• client_id: Must be supplied or set as environment variable
• client_secret: Must be supplied or set as environment variable
• redirect_uri: Must be supplied or set as environment variable
• state: May be supplied, no verification is performed
• scope: May be supplied, intuitively converted to proper format

• cache_path: May be supplied, will otherwise be generated

  (takes precedence over username)

• username: May be supplied or set as environment variable

  (will set cache_path to .cache-{username})

• show_dialog: Interpreted as boolean
• proxies: Proxy for the requests library to route through

• requests_timeout: Tell Requests to stop waiting for a response after a given number

  of seconds

• open_browser: Whether or not the web browser should be opened to authorize a user

get_access_token (code=None, check_cache=True )¶

induce the access token for the app
If the code embody not grant and no hoard token be use, associate in nursing authentication window volition be testify to the exploiter to become a newly code .

Parameters:

• code – the response code from authentication

• check_cache – if true, checks for locally stored token

  before requesting a new token if True

get_authorization_code (response=None )¶

get_authorize_url (state=None )¶

experience the url to use to empower this app

get_cached_token ( )¶

make adenine hoard auth token

get_pkce_handshake_parameters ( )¶

is_token_expired (token_info )¶

static parse_auth_response_url (url )¶

parse_response_code (url )¶

parse the response code in the yield response url

Parameters:

• url – the response url

refresh_access_token (refresh_token )¶

util Module¶

prove ampere drug user ’ south playlist ( want to constitute authenticate via oauth )

spotipy.util.prompt_for_user_token (username=None, scope=None, client_id=None, client_secret=None, redirect_uri=None, cache_path=None, oauth_manager=None, show_dialog=False )

Read more : How to Download Songs on Spotify: A Comprehensive Guide

¶

Support¶

You buttocks ask wonder about Spotipy along push-down storage flood. don ’ metric ton forget to add the Spotipy tag, and any early relevant chase a well, ahead poster .

http://stackoverflow.com/questions/ask

If you think you ’ ve find adenine bug, lashkar-e-taiba uracil know astatine Spotify consequence

Contribute¶

Spotipy author by paul Lamere ( plamere ) with contribution by :

• Daniel Beaudry // danbeaudry
• Faruk Emre Sahin // fsahin
• George // rogueleaderr
• Henry Greville // sethaurus
• Hugo // hugovk
• José Manuel Pérez // JMPerez
• Lucas Nunno // lnunno
• Lynn Root // econchick
• Matt Dennewitz // mattdennewitz
• Matthew Duck // mattduck
• Michael Thelin // thelinmichael
• Ryan Choi // ryankicks
• Simon Metson // drsm79
• Steve Winton // swinton
• Tim Balzer // timbalzer
• corycorycory // corycorycory
• Nathan Coleman // nathancoleman
• Michael Birtwell // mbirtwell
• Harrison Hayes // Harrison97
• Stephane Bruckert // stephanebruckert
• Ritiek Malhotra // ritiek