Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
372 lines (280 sloc) 11.3 KB

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.

Even if your script does not have an accessible URL you need to specify one when registering your application where the spotify authentication API will redirect to after successful login. The URL doesn't need to work or be accessible, you can specify "http://localhost/", after successful login you just need to copy the "http://localhost/?code=..." URL from your browser and paste it to the console where your script is running.

Register your app at My Applications.

spotipy supports two authorization flows:

  • The Authorization Code flow This method is suitable for long-running applications which the user logs into once. It provides an access token that can be refreshed.
  • The Client Credentials flow The method makes it possible to authenticate your requests to the Spotify Web API and to obtain a higher rate limit than you would

Authorization Code Flow

To support the Authorization Code Flow 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:

util.prompt_for_user_token(username,scope,client_id='your-app-redirect-url',client_secret='your-app-redirect-url',redirect_uri='your-app-redirect-url')

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 and ask for the SPOTIPY_REDIRECT_URI you were redirected to with the authorization token appended. 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

Client Credentials Flow

To support the Client Credentials Flow Spotipy provides a class SpotifyClientCredentials that can be used to authenticate requests like so:

import spotipy
from spotipy.oauth2 import SpotifyClientCredentials

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

playlists = sp.user_playlists('spotify')
while playlists:
    for i, playlist in enumerate(playlists['items']):
        print("%4d %s %s" % (i + 1 + playlists['offset'], playlist['uri'],  playlist['name']))
    if playlists['next']:
        playlists = sp.next(playlists)
    else:
        playlists = None

Client credentials flow is appropriate for requests that do not require access to a user's private data. Even if you are only making calls that do not require authorization, using this flow yields the benefit of a higher rate limit

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

:mod:`client` Module

.. automodule:: spotipy.client
    :members:
    :undoc-members:
    :special-members: __init__
    :show-inheritance:

:mod:`oauth2` Module

.. automodule:: spotipy.oauth2
    :members:
    :undoc-members:
    :special-members: __init__
    :show-inheritance:

:mod:`util` Module

.. automodule:: spotipy.util
    :members:
    :undoc-members:
    :special-members: __init__
    :show-inheritance:


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.

http://stackoverflow.com/questions/ask

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
  • Nathan Coleman // nathancoleman
  • Michael Birtwell // mbirtwell

License

https://github.com/plamere/spotipy/blob/master/LICENSE.txt

Indices and tables