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.

Assuming you set the SPOTIPY_CLIENT_ID and SPOTIPY_CLIENT_SECRET environment variables, here's a quick example of using Spotipy to list the names of all the albums released by the artist 'Birdy':

import spotipy
from spotipy.oauth2 import SpotifyClientCredentials

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

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
from spotipy.oauth2 import SpotifyClientCredentials

lz_uri = 'spotify:artist:36QJpDe2go2KgaRleHCDTp'

spotify = spotipy.Spotify(client_credentials_manager=SpotifyClientCredentials())
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
from spotipy.oauth2 import SpotifyClientCredentials

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

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 or upgrade Spotipy with:

pip install spotipy --upgrade

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

Getting Started

All methods require user authorization. You will need to register your app at My Dashboard to get the credentials necessary to make authorized calls (a client id and client secret).

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.

Note

Requires you to add a redirect URI to your application at My Dashboard. See Redirect URI for more details.

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 with the Authorization Code flow.

Authorization Code Flow

This flow is suitable for long-running applications in which the user grants permission only once. It provides an access token that can be refreshed. Since the token exchange involves sending your secret key, perform this on a secure location, like a backend service, and not from a client such as a browser or from a mobile app.

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-spotify-client-id',
                           client_secret='your-spotify-client-secret',
                           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 (use SET instead of export on Windows):

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 the util.prompt_for_user_token method with the username, the desired scope (see Using Scopes for information about scopes) and credentials (passed directly or via environment variables) to start the authorization process.

Redirect URI

For the Authorization Code Flow you need to add a redirect URI to your application at My Dashboard (navigate to your application and then [Edit Settings]).

The redirect_uri argument or SPOTIPY_REDIRECT_URI environment variable must match the redirect URI added to your application in your Dashboard. The redirect URI can be any valid URI (it does not need to be accessible) such as http://example.com, http://localhost or http://127.0.0.1:9090.

Calling util.prompt_for_user_token will open Spotify's application authorization page in your browser (and require you to log in if you are not already logged in to spotify.com), unless a locally cached access token exist from a previous authorization/authentication.

After successful authentication your browser will be redirected to the redirect URI of your application, e.g. http://localhost:9090/?code=<code>.

If your request URI is set to http://127.0.0.1:<port> or http://localhost:<port> Spotipy will automatically complete the authorization process (obtain the <code> from the URI).

If your request URI is set to any other URI you will need to manually copy the URI from the browser's address bar and paste it into the terminal/console where your Spotipy script is running (Spotipy will instruct you to do so).

Example

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

The Client Credentials flow is used in server-to-server authentication. Only endpoints that do not access user information can be accessed. The advantage here in comparison with requests to the Web API made without an access token, is that a higher rate limit is applied.

As opposed to the Authorization Code Flow, you will not need to set SPOTIPY_REDIRECT_URI, which means you will never be redirected to the sign in page in your browser:

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

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

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, this time using the Authorization Code Flow to access your personal Spotify account data.

Add tracks to a playlist:

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.playlist(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

Harrison Hayes // Harrison97

Stephane Bruckert // stephanebruckert

Ritiek Malhotra // ritiek

License

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

Indices and tables

:ref:`genindex`
:ref:`modindex`
:ref:`search`

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

index.rst

index.rst

Welcome to Spotipy!

Features

Installation

Getting Started

Authorization Code Flow

Redirect URI

Example

Client Credentials Flow

IDs URIs and URLs

Examples

More Examples

API Reference

:mod:`client` Module

:mod:`oauth2` Module

:mod:`util` Module

Support

Contribute

License

Indices and tables

Files

index.rst

Latest commit

History

index.rst

File metadata and controls

Welcome to Spotipy!

Features

Installation

Getting Started

Authorization Code Flow

Redirect URI

Example

Client Credentials Flow

IDs URIs and URLs

Examples

More Examples

API Reference

:mod:`client` Module

:mod:`oauth2` Module

:mod:`util` Module

Support

Contribute

License

Indices and tables