To use the Web API, you’ll need to register an application. From its page retrieve the client ID and secret. They are your application’s credentials to the API. A walkthrough of creating an application and setting it up can be found here.
Retrieving a client token
First we’ll retrieve a client token for the Spotify application. It is a token associated with your application and can be used to make basic calls to the API.
Calling the API
Next the Spotify object should be created. The following script will list the track numbers and names of songs on an album given the album ID.
Response attributes can be directly accessed with dot notation as above. To quickly inspect a response or any part of it, print its contents.
Retrieving a user token
Many endpoints require user authorisation, for which another type of access token is needed. User tokens are associated with a Spotify user account.
Retrieving them requires some more setting up.
A redirect URI should be whitelisted in application settings.
It is the address to which users are redirected
after authorising the application.
Alternatively, the default redirect URI
can be used with a client with no other redirect URIs whitelisted.
Different privileges or scopes can be requested when authorising. Below we’ll retrieve a token that has every possible scope. The script will open a web page prompting for a Spotify login. The user is then redirected back to the whitelisted redirect URI. Paste the redirected URI in full to the shell to finalise token retrieval.
prompt_for_user_token() eliminates the need for a web server,
which would normally be used to complete authorisation,
by requesting the user to manually enter information to the shell.
However, that also makes it unusable on a server.
Other authorisation methods are introduced in Authorisation guide.
Calling the API as a user
The following script replaces the application token with a user token and lists some of the user’s most listened tracks.
The snippet below will play Sibelius’ Finlandia if the user has a recently used Spotify application open. If no active device is found, an error is thrown.
finlandia = '3hHWhvw2hjwfngWcFjIzqr'
Saving the configuration
Currently, we need to go through the authorisation process every time the script is run. Let’s save the configuration to avoid this in the future.
Now we can replace the authorisation lines with reconstructing the token.
This approach is not scalable to multi-user scenarios. See Authorisation guide for more information.
How to read the documentation
The reference documentation is built for easy navigation.
Each endpoint (like
a description, required and optional scopes, arguments and return information.
Notably, the return type often contains a link to the relevant response model.
Follow them to discover the attributes that a model has.
Further links can be followed down the model hierarchy.
Our Authorisation guide details different authorisation options. Advanced usage provides an overview of things to keep in mind when building an actual application and what Tekore has to offer for that. You could also have a look at some example scripts to start familiarising yourself with the Web API.