__init__

Spotify Web API Python3 Library

Overview

This API provides Python programmers the ability to retrieve information from the Spotify Web API from any program written in Python 3. It also allows player control via Spotify Connect devices.

More information about the Spotify Web API can be found on the Spotify Developer Portal page.

IMPORTANT This API assumes you will adhere to all of the terms set forth in the Spotify Developer Terms of Use. The developers of this API are not responsible for misuse of the underlying Spotify Web API.

Features

This API supports all of the features of the Spotify Web API including access to all end points, and support for user authorization with scope(s). Check out the Spotify Web API documentation page for more details.

The following features are supported by this API.

  • Authorization: Token generation (Authorization Code, Authorization Code PKCE, Client Credentials) with Scope(s), auto token storage and renewal.
  • Albums: Get Album(s), Get Album Tracks, User Favorites (Get,Add,Remove,Check), Get New Releases.
  • Artists: Get Artist(s), Get Artist's Albums, Get Artist's Top Tracks, Get Related Artists.
  • Audiobooks: Get Audiobook(s), Get Audiobook Chapters, User Favorites (Get,Add,Remove,Check).
  • Categories: Get Several Browse Categories, Get Single Browse Category.
  • Chapters: Get a Chapter, Get Several Chapters.
  • Episodes: Get Episode(s), User Favorites (Get,Add,Remove,Check).
  • Genres: Get Available Genre Seeds.
  • Markets: Get Available Markets.
  • Player: Get Playback State, Transfer Playback, Get Available Devices, Get Currently Playing Track, Start/Resume/Pause/Skip/Seek/Repeat/Shuffle/Volume Playback, Get Recently Played Tracks, Get the User's Queue, Add Item to Playback Queue.
  • Playlists: Get Playlist(s), Change Playlist Details, Get/Update/Add/Remove Playlist Items, Get Favorites, Get User's Playlists, Create Playlist, Get Featured Playlists, Get Category's Playlists, Get Playlist Cover Image, Add Custom Playlist Cover Image
  • Search: Search for Albums/Artists/Audiobooks/Episodes/Playlists/Shows/Tracks.
  • Shows: Get Show(s), Get Show Episodes, User Favorites (Get,Add,Remove,Check).
  • Tracks: Get Track(s), User Favorites (Get,Add,Remove,Check), Get Track(s) Audio Features, Recommendations, Analysis.
  • Users: Get Current/Another User's Profile, Get Top Items, Favorites (Follow,Unfollow,Check) Artists/Playlist/Users.
  • Supports caching of rarely changed configuration data: Categories, Devices, Genres, Markets, UserProfile, etc.
  • ... and more

Requirements and Dependencies

The following requirements must be met in order to utilize this API:

  • You must have a Spotify account (free or premium). Note that some API functions require a PREMIUM account in order to work. Check the Spotify Developer Documentation pages for more details.
  • You will need to create a Spotify App in order to access the Spotify Web API. An App provides the Client ID and Client Secret needed to request an access token by implementing any of the OAuth2 authorization flows. More information about creating an application can be found on the Spotify Getting started with Web API page.

The following Python-related requirements must be met in order to utilize this API:

  • Python 3.4 or greater (Python 2 not supported).
  • oauthlib (==3.2.2) - for OAuth support.
  • platformdirs (==4.1.0) - for platform dependent directory support.
  • smartinspectPython (==3.0.30) - for diagnostics and logging support.
  • requests (==2.31.0) - for web service request support.
  • requests_oauthlib (==1.3.1) - for OAuth support.
  • urllib3 (==2.1.0) - for web service request support.

Documentation

Documentation is located in the package library under the 'docs' folder; use the index.html as your starting point. You can also view the latest docs on the readthedocs web-site.

Installation

This module can be easily installed via pip:

$ python3 -m pip install spotifywebapipython

Quick-Start Sample Code

Almost every method is documented with sample code; just click on the "Sample Code" links under the method, and use the "Copy to Clipboard" functionality to copy / paste.

Check out the following classes to get you started:

Licensing

This project is licensed and distributed under the terms of the MIT End-User License Agreement (EULA) license.

Logging / Tracing Support

The SmartInspectPython package (installed with this package) can be used to easily debug your applications that utilize this API.

The following topics and code samples will get you started on how to enable logging support.
Note that logging support can be turned on and off without changing code or restarting the application.
Click on the topics below to expand the section and reveal more information.

Configure Logging Support Settings File
Add the following lines to a new file (e.g. "smartinspect.cfg") in your application startup / test directory.
Note the file name can be whatever you like, just specify it on the call to SiAuto.Si.LoadConfiguration() when initializing the logger.

; smartinspect.cfg

; SmartInspect Logging Configuration General settings.
; - "Enabled" parameter to turn logging on (True) or off (False).
; - "Level" parameter to control the logging level (Debug|Verbose|Message|Warning|Error).
; - "AppName" parameter to control the application name.
Enabled = False 
Level = Verbose
DefaultLevel = Debug
AppName = My Application Name

; SmartInspect Logging Configuration Output settings.
; - Log to SmartInspect Console Viewer running on the specified network address.
Connections = tcp(host=192.168.1.1,port=4228,timeout=5000,reconnect=true,reconnect.interval=10s,async.enabled=true)
; - Log to a file, keeping 14 days worth of logs.
;Connections = "file(filename=\"./tests/logfiles/logfile.log\", rotate=daily, maxparts=14, append=true)"
; - Log to an encrypted file, keeping 14 days worth of logs.
;Connections = "file(filename=\"./tests/logfiles/logfileEncrypted.sil\", encrypt=true, key=""1234567890123456"", rotate=daily, maxparts=14, append=true)"

; set defaults for new sessions
; note that session defaults do not apply to the SiAuto.Main session, since
; this session was already added before a configuration file can be loaded. 
; session defaults only apply to newly added sessions and do not affect existing sessions.
SessionDefaults.Active = True
SessionDefaults.Level = Message
SessionDefaults.ColorBG = 0xFFFFFF

; configure some individual session properties.
; note that this does not add the session to the sessionmanager; it simply
; sets the property values IF the session name already exists.
Session.Main.Active = True
Session.Main.ColorBG = 0xFFFFFF

Initialize Logging Support, MAIN module
Add the following lines to your program startup module.
This will import the necessary package modules, and initialize logging support.
NOTE - This code should only be executed one time! 

# load SmartInspect settings from a configuration settings file.
from smartinspectpython.siauto import *
siConfigPath:str = "./tests/smartinspect.cfg"
SIAuto.Si.LoadConfiguration(siConfigPath)

# start monitoring the configuration file for changes, and reload it when it changes.
# this will check the file for changes every 60 seconds.
siConfig:SIConfigurationTimer = SIConfigurationTimer(SIAuto.Si, siConfigPath)

# get smartinspect logger reference.
_logsi:SISession = SIAuto.Main

# log system environment and application startup parameters.
_logsi.LogSeparator(SILevel.Fatal)
_logsi.LogAppDomain(SILevel.Verbose)
_logsi.LogSystem(SILevel.Verbose)

Initialize Logging Support, CLASS or sub-modules
Add the following lines to your program supporting modules.
This will import the necessary package modules, and initialize the shared logging session. 

# get smartinspect logger reference.
from smartinspectpython.siauto import *
_logsi:SISession = SIAuto.Main

More Information on SmartInspect
You can use SmartInspectPython by itself to create log files for your own applications.
Use the following PIP command to install the SmartInspectPython package from PyPi.org: 
$ python3 -m pip install smartinspectpython

The SmarrtInspect Redistributable Console Viewer (free) is required to view SmartInspect Log (.sil) formatted log files, as well capture packets via the TcpProtocol or PipeProtocol connections. The Redistributable Console Viewer can be downloaded from the Code-Partners Software Downloads Page. Note that the "Redistributable Console Viewer" is a free product, while the "SmartInspect Full Setup" is the Professional level viewer that adds a few more bells and whistles for a fee. Also note that a Console Viewer is NOT required to view plain text (non .sil) formatted log files.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

  1. Fork the Project
  2. Create your Feature Branch git checkout -b feature/AmazingFeature
  3. Commit your Changes git commit -m 'Add some AmazingFeature'
  4. Push to the Branch git push origin feature/AmazingFeature
  5. Open a Pull Request

View Change Log

Change Log

All notable changes to this project are listed here.

Change are listed in reverse chronological order (newest to oldest).

[ 1.0.29 ] - 2024/02/23
  • Added ContainsId method to the following classes: AlbumPageSimplified, AudiobookPageSimplified, ChapterPageSimplified, EpisodePageSimplified, PlaylistPageSimplified, ShowPageSimplified, and TrackPageSimplified.
  • Updated SpotifyClient.GetPlayerRecentTracks method with auto-pagination support to retrieve ALL available items (or up to a limit total).
[ 1.0.28 ] - 2024/02/21
  • Added SpotifyClient.SearchAlbums method to search Spotify for matching Album criteria.
  • Added SpotifyClient.SearchArtists method to search Spotify for matching Artist criteria.
  • Added SpotifyClient.SearchAudiobooks method to search Spotify for matching Audiobook criteria.
  • Added SpotifyClient.SearchEpisodes method to search Spotify for matching Episode criteria.
  • Added SpotifyClient.SearchPlaylists method to search Spotify for matching Playlist criteria.
  • Added SpotifyClient.SearchShows method to search Spotify for matching Show criteria.
  • Added SpotifyClient.SearchTracks method to search Spotify for matching Track criteria.
  • Updated SpotifyClient methods to add auto-pagination to retrieve ALL available items (or up to a limit total). Methods modified were: GetAlbumFavorites, GetAlbumNewReleases, GetArtistAlbums, GetArtistsFollowed, GetCategoryPlaylists, GetFeaturedPlaylists, GetPlaylistFavorites, GetPlaylistsForUser, GetPlaylistItems, GetAlbumTracks, GetAudiobookChapters, GetAudiobookFavorites, GetBrowseCategorys, GetEpisodeFavorites, GetShowEpisodes, GetShowFavorites, GetTrackFavorites, GetUsersTopArtists, GetUsersTopTracks.
  • Renamed SpotifyClient.GetBrowseCategorys method to GetBrowseCategorysList.
  • Renamed SpotifyClient.GetBrowseCategorysByPage method to GetBrowseCategorys.
  • Added Category.Uri property to simulate a Spotify-like Uri value for a category. This is a helper property - no value with this name is returned from the Spotify Web API.
  • Updated PageObject model with property setters for the CursorBefore, CursorAfter, Limit, Offset and Total properties. This allows a user to modify the values when performing custom paging operations.
  • Updated all SpotifyClient methods that utilize a market argument to ensure that a market value was either supplied or implied (using an authorization access token with a user profile). The Spotify Web API was returning null results for some methods that did not supply a market value while using a public access token (e.g. no country code default).
[ 1.0.27 ] - 2024/02/20
  • Updated SpotifyClient.GetPlayerRecentTracks method to retrieve the last 24 hours of play history if neither after or before arguments were specified.
[ 1.0.26 ] - 2024/02/15
  • Added SpotifyClient.ToString method to display a string representation of the class.
  • Added SpotifyClient.ConfigurationCache property to store static configuration objects.
  • Added SpotifyClient.ClearConfigurationCache method to clear the configuration cache.
  • Updated SpotifyClient methods to add returned results to the ConfigurationCache for faster access: GetBrowseCategory, GetBrowseCategorys, GetGenres, GetMarkets, GetPlayerDevice, GetPlayerDevices, GetUsersCurrentProfile. This increases performance when accessing Spotify information that rarely changes.
[ 1.0.25 ] - 2024/02/10
  • Updated urllib3 requirements to "urllib3>=1.21.1,<1.27", to ensure urllib3 version 2.0 is not used. Home Assistant requires urllib3 version less than 2. This was causing intermittent issues with calling requests resulting in **kwargs errors when used in Home Assistant!
[ 1.0.24 ] - 2024/02/10
  • Updated SpotifyClient.MakeRequest method to pass ALL parameters in the various request methods. Prior to this fix, there were urllib3 request issues with **KWARGS while using the api in a Home Assistant integration.
[ 1.0.23 ] - 2024/02/09
  • Updated SpotifyClient.MakeRequest method to use json library to create JSON request body, instead of the urllib3 request(...,json=...) method. The urllib3 request class seems to have issues processing json data.
[ 1.0.22 ] - 2024/02/09
  • Added SpotifyClient.GetIdFromUri method to return the Id portion of a Uri value.
  • Added SpotifyClient.GetTypeFromUri method to return the Type portion of a Uri value.
  • Updated SpotifyClient.GetPlayerDevice method to return a selected device by id or name.
  • Added SpotifyDiscovery class that discovers Spotify Connect devices via Zeroconf.
  • Updated UserProfileSimplified method to default the DisplayName property to the Id property value if a display name was not set.
[ 1.0.21 ] - 2024/02/08
  • Added SearchResponse.GetSpotifyOwnedPlaylists method that gets a list of all playlist items in the underlying search response that have an owner of spotify:user:spotify. These are playlists that are generated for you by the spotify ai engine.
  • Added additionalTypes argument to SpotifyClient.GetPlayerPlaybackState method.
  • Added additionalTypes argument to SpotifyClient.GetPlayerNowPlaying method.
  • Updated SpotifyClient.GetPlayerDevices method to return the list of devices in sorted order by Name.
[ 1.0.20 ] - 2024/02/07
  • Added PlayHistoryPage.GetTracks method that gets a list of all tracks contained in the underlying PlayHistory list. This is a convenience method so one does not have to loop through the PlayHistory array of Track objects to get the list of tracks.
[ 1.0.19 ] - 2024/02/07
  • Updated TrackPageSaved model to parse a Track object instead of a TrackSimplified object. The Track object contains the extra Album, ExternalIds and Popularity properties.
  • Updated TrackRecommendations model to parse a Track object instead of a TrackSimplified object. The Track object contains the extra Album, ExternalIds and Popularity properties.
  • Added AlbumPageSaved.GetAlbums method that gets a list of all albums contained in the underlying Items list. This is a convenience method so one does not have to loop through the Items array of AlbumSaved objects to get the list of albums.
  • Added TrackPageSaved.GetTracks method that gets a list of all tracks contained in the underlying Items list. This is a convenience method so one does not have to loop through the Items array of TrackSaved objects to get the list of tracks.
  • Added EpisodePageSaved.GetEpisodes method that gets a list of all episodes contained in the underlying Items list. This is a convenience method so one does not have to loop through the Items array of EpisodeSaved objects to get the list of episodes.
  • Added ShowPageSaved.GetShows method that gets a list of all shows contained in the underlying Items list. This is a convenience method so one does not have to loop through the Items array of ShowSaved objects to get the list of shows.
  • Added an ImageUrl property to all models that have an Images collection. The new property returns the first image url in the Images list, if images are defined; otherwise, null. This is a convenience method so one does not have to loop through the Images array of ImageObject objects to get an image url.
[ 1.0.18 ] - 2024/02/05
  • Updated SpotifyClient methods to set the request header authorization key directly, rather than assigning a new dictionary to the value.
  • Updated SpotifyClient.MakeRequest method to apply token refresh changes to the request authorization header if present. Prior to this fix, the request was still referencing the expired token value.
  • Added SpotifyAuthToken.HeaderKey property for request header access.
  • Added SpotifyAuthToken.HeaderValue property for request header access.
  • Removed SpotifyAuthToken.GetHeaders method, as it was no longer required.
[ 1.0.17 ] - 2024/02/04
  • Updated SpotifyClient to correctly support the tokenUpdater callable to update a token for an external provider.
  • Updated AuthClient to correctly support the tokenUpdater callable to update a token for an external provider.
[ 1.0.16 ] - 2024/02/02
  • Updated numerous classes with a ToDictionary method to allow dictionary representation of data.
[ 1.0.15 ] - 2024/02/02
  • Updated SpotifyClient methods with better logging information.
  • Updated AuthClient methods with better logging information.
[ 1.0.14 ] - 2024/02/01
  • Updated SpotifyClient methods to add basic validation for required parameter values.
[ 1.0.13 ] - 2024/02/01
  • Updated SpotifyClient._CheckResponseForErrors method to use json library to parse JSON response, instead of the urllib3 HTTPResponse.json() method. The urllib3 HTTPResponse class can return missing attributes and methods when processing redirects.
[ 1.0.12 ] - 2024/02/01
  • Updated SpotifyClient._CheckResponseForErrors method with better logging information.
[ 1.0.11 ] - 2024/02/01
  • Updated SpotifyClient._CheckResponseForErrors method with better logging information.
[ 1.0.10 ] - 2024/02/01
  • Added SpotifyClient.SetAuthTokenFromToken method to allow the authorization token to be used from an existing OAuth2 token.
  • Removed SpotifyClient.SetAuthTokenFromSession method in favor of the SetAuthTokenFromToken method.
  • Updated scope processing to pass a space-delimited string of scopes instead of an array of strings. It appears that the Spotify Web API will accept both, but API documentation states that a space-delimited string is preferred.
[ 1.0.9 ] - 2024/01/31
  • Updated SpotifyClient.SetAuthTokenFromSession method to correct a bug related to Home Assistant OAuth2Session object.
[ 1.0.8 ] - 2024/01/31
  • Added SpotifyClient.SetAuthTokenFromSession method to allow the authorization token to be used from an existing OAuth2Session.
[ 1.0.7 ] - 2024/01/29
  • Allow customization of the redirect uri host and port values in the token authorization process.
[ 1.0.6 ] - 2024/01/29
  • Changed urllib3 requirements to a non-specific version so it could run with Home Assistant addons.
[ 1.0.5 ] - 2024/01/29
  • Changed Development Status to 5 - Production / Stable.
[ 1.0.4 ] - 2024/01/29
  • Removed invalid requirement from setup.py.
[ 1.0.3 ] - 2024/01/29
  • Added SpotifyAuthToken.ProfileId property that indicates the token profile that was loaded.
[ 1.0.2 ] - 2024/01/29
  • Corrected the SpotifyClient.GetTrackRecommendations method to process the market, maxSpeechiness, and targetSpeechiness arguments correctly.
  • Updated SpotifyClient.SetAuthTokenAuthorizationCode method to use a 120 second timeout value while waiting for an authorize response from the user.
  • Updated SpotifyClient.SetAuthTokenAuthorizationCodePkce method to use a 120 second timeout value while waiting for an authorize response from the user.
[ 1.0.1 ] - 2024/01/17
  • Version 1 initial release.