_images/spotify-web-api-doc.jpg

Welcome to Spotipy!

Spotipy is a lightweight Python library for the Spotify Web API. With Spotipy you get full access to all of the music data provided by the Spotify platform.

Here’s a quick example of using Spotipy to list the names of all the albums released by the artist ‘Birdy’:

import spotipy

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

results = spotify.artist_albums(birdy_uri, album_type='album')
albums = results['items']
while results['next']:
    results = spotify.next(results)
    albums.extend(results['items'])

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

Here’s another example showing how to get 30 second samples and cover art for the top 10 tracks for Led Zeppelin:

import spotipy

lz_uri = 'spotify:artist:36QJpDe2go2KgaRleHCDTp'

spotify = spotipy.Spotify()
results = spotify.artist_top_tracks(lz_uri)

for track in results['tracks'][:10]:
    print 'track    : ' + track['name']
    print 'audio    : ' + track['preview_url']
    print 'cover art: ' + track['album']['images'][0]['url']
    print

Finally, here’s an example that will get the URL for an artist image given the artist’s name:

import spotipy
import sys

spotify = spotipy.Spotify()

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

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

Features

Spotipy supports all of the features of the Spotify Web API including access to all end points, and support for user authorization. For details on the capabilities you are encouraged to review the Spotify Web API documentation.

Installation

Install Spotipy with:

pip install spotipy

Or with:

easy_install spotipy

Or you can get the source from github at https://github.com/plamere/spotipy

Getting Started

Non-Authorized requests

For methods that do not require authorization, simply create a Spotify object and start making method calls like so:

import spotipy
spotify = spotipy.Spotify()
results = spotify.search(q='artist:' + name, type='artist')
print results

Authorized requests

Many methods require user authentication. For these requests you will need to generate an authorization token that indicates that the user has granted permission for your application to perform the given task. You will need to register your app to get the credentials necessary to make authorized calls. Register your app at My Applications.

Spotipy provides a utility method util.prompt_for_user_token that will attempt to authorize the user. You can pass your app credentials directly into the method as arguments, or if you are reluctant to immortalize your app credentials in your source code, you can set environment variables like so:

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

Call util.prompt_for_user_token method with the username and the desired scope (see Using Scopes for information about scopes) and credentials. This will coordinate the user authorization via your web browser. The credentials are cached locally and are used to automatically re-authorized expired tokens.

Here’s an example of getting user authorization to read a user’s saved tracks:

import sys
import spotipy
import spotipy.util as util

scope = 'user-library-read'

if len(sys.argv) > 1:
    username = sys.argv[1]
else:
    print "Usage: %s username" % (sys.argv[0],)
    sys.exit()

token = util.prompt_for_user_token(username, scope)

if token:
    sp = spotipy.Spotify(auth=token)
    results = sp.current_user_saved_tracks()
    for item in results['items']:
        track = item['track']
        print track['name'] + ' - ' + track['artists'][0]['name']
else:
    print "Can't get token for", username

IDs URIs and URLs

Spotipy supports a number of different ID types:

  • 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: http://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

In general, any Spotipy method that needs an artist, album, track or playlist ID will accept ids in any of the above form

Examples

Here are a few more examples of using Spotipy.

Add tracks to a playlist:

import pprint
import sys

import spotipy
import spotipy.util as util

if len(sys.argv) > 3:
    username = sys.argv[1]
    playlist_id = sys.argv[2]
    track_ids = sys.argv[3:]
else:
    print "Usage: %s username playlist_id track_id ..." % (sys.argv[0],)
    sys.exit()

scope = 'playlist-modify-public'
token = util.prompt_for_user_token(username, scope)

if token:
    sp = spotipy.Spotify(auth=token)
    sp.trace = False
    results = sp.user_playlist_add_tracks(username, playlist_id, track_ids)
    print results
else:
    print "Can't get token for", username

Shows the contents of every playlist owned by a user:

# shows a user's playlists (need to be authenticated via oauth)

import sys
import spotipy
import spotipy.util as util

def show_tracks(tracks):
    for i, item in enumerate(tracks['items']):
        track = item['track']
        print "   %d %32.32s %s" % (i, track['artists'][0]['name'],
            track['name'])


if __name__ == '__main__':
    if len(sys.argv) > 1:
        username = sys.argv[1]
    else:
        print "Whoops, need your username!"
        print "usage: python user_playlists.py [username]"
        sys.exit()

    token = util.prompt_for_user_token(username)

    if token:
        sp = spotipy.Spotify(auth=token)
        playlists = sp.user_playlists(username)
        for playlist in playlists['items']:
            if playlist['owner']['id'] == username:
                print
                print playlist['name']
                print '  total tracks', playlist['tracks']['total']
                results = sp.user_playlist(username, playlist['id'],
                    fields="tracks,next")
                tracks = results['tracks']
                show_tracks(tracks)
                while tracks['next']:
                    tracks = sp.next(tracks)
                    show_tracks(tracks)
    else:
        print "Can't get token for", username

More Examples

There are many more examples of how to use Spotipy in the Examples Directory on Github

API Reference

client Module

class spotipy.client.Spotify(auth=None, requests_session=True, client_credentials_manager=None)

Bases: object

Example usage:

import spotipy

urn = 'spotify:artist:3jOstUTkEu2JkjvRdBA5Gu'
sp = spotipy.Spotify()

sp.trace = True # turn on tracing
sp.trace_out = True # turn on trace out

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

user = sp.user('plamere')
print(user)
__init__(auth=None, requests_session=True, client_credentials_manager=None)

Create a Spotify API object.

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
album(album_id)

returns a single album given the album’s ID, URIs or URL

Parameters:
  • album_id - the album ID, URI or URL
album_tracks(album_id, limit=50, offset=0)

Get Spotify catalog information about an album’s tracks

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
albums(albums)

returns a list of albums given the album IDs, URIs, or URLs

Parameters:
  • albums - a list of album IDs, URIs or URLs
artist(artist_id)

returns a single artist given the artist’s ID, URI or URL

Parameters:
  • artist_id - an artist ID, URI or URL
artist_albums(artist_id, album_type=None, country=None, limit=20, offset=0)

Get Spotify catalog information about an artist’s albums

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

Get Spotify catalog information about artists similar to an identified artist. Similarity is based on analysis of the Spotify community’s listening history.

Parameters:
  • artist_id - the artist ID, URI or URL
artist_top_tracks(artist_id, country='US')

Get Spotify catalog information about an artist’s top 10 tracks by country.

Parameters:
  • artist_id - the artist ID, URI or URL
  • country - limit the response to one particular country.
artists(artists)

returns a list of artists given the artist IDs, URIs, or URLs

Parameters:
  • artists - a list of artist IDs, URIs or URLs
audio_features(tracks=[])

Get audio features for multiple tracks based upon their Spotify IDs Parameters:

  • tracks - a list of track URIs, URLs or IDs, maximum: 50 ids
categories(country=None, locale=None, limit=20, offset=0)

Get a list of new album releases featured in Spotify

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_playlists(category_id=None, country=None, limit=20, offset=0)

Get a list of new album releases featured in Spotify

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.
current_user()

Get detailed profile information about the current user. An alias for the ‘me’ method.

current_user_followed_artists(limit=20, after=None)

Gets a list of the artists followed by the current authorized user

Parameters:
  • limit - the number of tracks to return
  • after - ghe last artist ID retrieved from the previous request
current_user_saved_albums(limit=20, offset=0)

Gets a list of the albums saved in the current authorized user’s “Your Music” library

Parameters:
  • limit - the number of albums to return
  • offset - the index of the first album to return
current_user_saved_tracks(limit=20, offset=0)

Gets a list of the tracks saved in the current authorized user’s “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=[])

Add one or more tracks to the current user’s “Your Music” library.

Parameters:
  • tracks - a list of track URIs, URLs or IDs
current_user_saved_tracks_contains(tracks=[])

Check if one or more tracks is already saved in the current Spotify user’s “Your Music” library.

Parameters:
  • tracks - a list of track URIs, URLs or IDs
current_user_saved_tracks_delete(tracks=[])

Remove one or more tracks 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')

Get the current user’s top artists

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

Get the current user’s top tracks

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
featured_playlists(locale=None, country=None, timestamp=None, limit=20, offset=0)

Get a list of Spotify featured playlists

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_get_retries = 10
me()

Get detailed profile information about the current user. An alias for the ‘current_user’ method.

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

Get a list of new album releases featured in 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)

returns the next result given a paged result

Parameters:
  • result - a previously returned paged result
previous(result)

returns the previous result given a paged result

Parameters:
  • result - a previously returned paged result
recommendation_genre_seeds()

Get a list of genres available for the recommendations function.

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

Get a list of recommended tracks for one to five seeds.

Parameters:
  • seed_artists - a list of artist IDs, URIs or URLs
  • seed_tracks - a list of artist 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_<attribute> - For the tuneable track attributes listed in the documentation, these values provide filters and targeting on results.
search(q, limit=10, offset=0, type='track')

searches for an item

Parameters:
  • q - the search query

  • limit - the number of items to return

  • offset - the index of the first item to return

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

    ‘track’ or ‘playlist’

trace = False
trace_out = False
track(track_id)

returns a single track given the track’s ID, URI or URL

Parameters:
  • track_id - a spotify URI, URL or ID
tracks(tracks)

returns a list of tracks given a list of track IDs, URIs, or URLs

Parameters:
  • tracks - a list of spotify URIs, URLs or IDs
user(user)

Gets basic profile information about a Spotify User

Parameters:
  • user - the id of the usr
user_playlist(user, playlist_id=None, fields=None)

Gets playlist of a user Parameters:

  • user - the id of the user
  • playlist_id - the id of the playlist
  • fields - which fields to return
user_playlist_add_tracks(user, playlist_id, tracks, position=None)

Adds tracks to a playlist

Parameters:
  • user - the id of the user
  • playlist_id - the id of the playlist
  • tracks - a list of track URIs, URLs or IDs
  • position - the position to add the tracks
user_playlist_create(user, name, public=True)

Creates a playlist for a user

Parameters:
  • user - the id of the user
  • name - the name of the playlist
  • public - is the created playlist public
user_playlist_remove_all_occurrences_of_tracks(user, playlist_id, tracks, snapshot_id=None)

Removes all occurrences of the given tracks from the given 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
  • snapshot_id - optional id of the playlist snapshot
user_playlist_remove_specific_occurrences_of_tracks(user, playlist_id, tracks, snapshot_id=None)

Removes all occurrences of the given tracks from the given playlist

Parameters:
  • user - the id of the user

  • playlist_id - the id of the playlist

  • tracks - an array of objects containing Spotify URIs of the tracks to remove with their current positions in the playlist. For example:
    [ { “uri”:”4iV5W9uYEdYUVa79Axb7Rh”, “positions”:[2] },

    { “uri”:”1301WleyT98MSxVHPZCA6M”, “positions”:[7] } ]

  • 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 tracks 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)

Replace all tracks in a 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, playlist_id=None, fields=None, limit=100, offset=0, market=None)

Get full details of the tracks of a playlist owned by a user.

Parameters:
  • user - the id of the user
  • 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.
user_playlists(user, limit=50, offset=0)

Gets playlists of a user

Parameters:
  • user - the id of the usr
  • limit - the number of items to return
  • offset - the index of the first item to return
exception spotipy.client.SpotifyException(http_status, code, msg)

Bases: exceptions.Exception

__init__(http_status, code, msg)

oauth2 Module

class spotipy.oauth2.SpotifyClientCredentials(client_id=None, client_secret=None)

Bases: object

OAUTH_TOKEN_URL = 'https://accounts.spotify.com/api/token'
__init__(client_id=None, client_secret=None)

You can either provid a client_id and client_secret to the constructor or set SPOTIPY_CLIENT_ID and SPOTIPY_CLIENT_SECRET environment variables

get_access_token()

If a valid access token is in memory, returns it Else feches a new token and returns it

class spotipy.oauth2.SpotifyOAuth(client_id, client_secret, redirect_uri, state=None, scope=None, cache_path=None)

Bases: object

Implements Authorization Code Flow for Spotify’s OAuth implementation.

OAUTH_AUTHORIZE_URL = 'https://accounts.spotify.com/authorize'
OAUTH_TOKEN_URL = 'https://accounts.spotify.com/api/token'
__init__(client_id, client_secret, redirect_uri, state=None, scope=None, cache_path=None)

Creates a SpotifyOAuth object

Parameters:
  • client_id - the client id of your app
  • client_secret - the client secret of your app
  • redirect_uri - the redirect URI of your app
  • state - security state
  • scope - the desired scope of the request
  • cache_path - path to location to save tokens
get_access_token(code)

Gets the access token for the app given the code

Parameters:
  • code - the response code
get_authorize_url()

Gets the URL to use to authorize this app

get_cached_token()

Gets a cached auth token

parse_response_code(url)

Parse the response code in the given response url

Parameters:
  • url - the response url
exception spotipy.oauth2.SpotifyOauthError

Bases: exceptions.Exception

util Module

spotipy.util.prompt_for_user_token(username, scope=None, client_id=None, client_secret=None, redirect_uri=None)

prompts the user to login if necessary and returns the user token suitable for use with the spotipy.Spotify constructor

Parameters:

  • username - the Spotify username
  • scope - the desired scope of the request
  • client_id - the client id of your app
  • client_secret - the client secret of your app
  • redirect_uri - the redirect URI of your app

Support

You can ask questions about Spotipy on Stack Overflow. Don’t forget to add the Spotipy tag, and any other relevant tags as well, before posting.

If you think you’ve found a bug, let us know at Spotify Issues

Contribute

Spotipy authored by Paul Lamere (plamere) with contributions 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

Indices and tables