
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 is a video explaining how to do so). For a longer tutorial with examples included, refer to this video playlist. Below is 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(auth_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.
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
auth_manager = SpotifyClientCredentials()
sp = spotipy.Spotify(auth_manager=auth_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
Customized token caching¶
Tokens are refreshed automatically and stored by default in the project main folder. As this might not suit everyone’s needs, spotipy provides a way to create customized cache handlers.
https://github.com/plamere/spotipy/blob/master/spotipy/cache_handler.py
The custom cache handler would need to be a class that inherits from the base
cache handler CacheHandler
. The default cache handler CacheFileHandler
is a good example.
An instance of that new class can then be passed as a parameter when
creating SpotifyOAuth
, SpotifyPKCE
or SpotifyImplicitGrant
.
The following handlers are available and defined in the URL above.
CacheFileHandler
MemoryCacheHandler
DjangoSessionCacheHandler
FlaskSessionCacheHandler
RedisCacheHandler
Feel free to contribute new cache handlers to the repo.
Examples¶
There are many more examples of how to use Spotipy in the Examples Directory on Github
API Reference¶
client
Module¶
oauth2
Module¶
util
Module¶
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 on Github)
Faruk Emre Sahin (fsahin on Github)
George (rogueleaderr on Github)
Henry Greville (sethaurus on Github)
Hugo van Kemanade (hugovk on Github)
José Manuel Pérez (JMPerez on Github)
Lucas Nunno (lnunno on Github)
Lynn Root (econchick on Github)
Matt Dennewitz (mattdennewitz on Github)
Matthew Duck (mattduck on Github)
Michael Thelin (thelinmichael on Github)
Ryan Choi (ryankicks on Github)
Simon Metson (drsm79 on Github)
Steve Winton (swinton on Github)
Tim Balzer (timbalzer on Github)
Nathan Coleman (nathancoleman on Github)
Michael Birtwell (mbirtwell on Github)
Harrison Hayes (Harrison97 on Github)
Stephane Bruckert (stephanebruckert on Github)
Ritiek Malhotra (ritiek on Github)
If you are a developer with Python experience, and you would like to contribute to Spotipy, please be sure to follow the guidelines listed below:
- Export the needed Environment variables:::
export SPOTIPY_CLIENT_ID=client_id_here export SPOTIPY_CLIENT_SECRET=client_secret_here export SPOTIPY_CLIENT_USERNAME=client_username_here # This is actually an id not spotify display name export SPOTIPY_REDIRECT_URI=http://localhost:8080 # Make url is set in app you created to get your ID and SECRET
- Create virtual environment, install dependencies, run tests:::
$ virtualenv –python=python3.7 env (env) $ pip install –user -e . (env) $ python -m unittest discover -v tests
Lint
- To automatically fix the code style:::
pip install autopep8 autopep8 –in-place –aggressive –recursive .
- To verify the code style:::
pip install flake8 flake8 .
- To make sure if the import lists are stored correctly:::
pip install isort isort . -c -v
Publishing (by maintainer)
Bump version in setup.py
Bump and date changelog
Add to changelog:
- ::
## Unreleased
// Add your changes here and then delete this line
Commit changes
Package to pypi:
- ::
python setup.py sdist bdist_wheel python3 setup.py sdist bdist_wheel twine check dist/* twine upload –repository-url https://upload.pypi.org/legacy/ –skip-existing dist/.(whl|gz|zip)~dist/*linux.whl
Create github release https://github.com/plamere/spotipy/releases with the changelog content for the version and a short name that describes the main addition
Build the documentation again to ensure it’s on the latest version
Changelog
Don’t forget to add a short description of your change in the CHANGELOG!
License¶
(Taken from https://github.com/plamere/spotipy/blob/master/LICENSE.md):
MIT License
Copyright (c) 2021 Paul Lamere
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
(the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.