Skip to content

Getting started with Web API

This tutorial will help you to make your first Web API call by retriving an artist's metadata. The steps to do so are the following:

  1. Create an app, if you haven't done so.
  2. Request an access token.
  3. Use the access token to request the artist data.

Here we go, let's rock & roll!

Prerequisites

  • This tutorial assumes you have a Spotify account (free or premium).
  • We will use cURL to make API calls. You can install it from here our using the package manager of your choice.

Set Up Your Account

Login to the Spotify Developer Dashboard. If necessary, read the latest Developer Terms of Service to complete your account set up.

Create an app

An app provides the Client ID and Client Secret needed to request an access token by implementing any of the authorization flows.

To create an app, go to your Dashboard, click on the Create an app button and enter the following information:

  • App Name: My App
  • App Description: This is my first Spotify app
  • Redirect URI: You won't need this parameter in this example, so let's use http://localhost:3000.

Finally, check the Developer Terms of Service checkbox and tap on the Create button.

Request an access token

The access token is a string which contains the credentials and permissions that can be used to access a given resource (e.g artists, albums or tracks) or user's data (e.g your profile or your playlists).

In order to request the access token you need to get your Client_ID and Client Secret:

  1. Go to the Dashboard
  2. Click on the name of the app you have just created (My App)
  3. Click on the Settings button

The Client ID can be found here. The Client Secret can be found behind the View client secret link.

With our credentials in hand, we are ready to request an access token. This tutorial uses the Client Credentials, so we must:

  • Send a POST request to the token endpoint URI.
  • Add the Content-Type header set to the application/x-www-form-urlencoded value.
  • Add a HTTP body containing the Client ID and Client Secret, along with the grant_type parameter set to client_credentials.

_10
curl -X POST "https://accounts.spotify.com/api/token" \
_10
-H "Content-Type: application/x-www-form-urlencoded" \
_10
-d "grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret"

The response will return an access token valid for 1 hour:


_10
{
_10
"access_token": "BQDBKJ5eo5jxbtpWjVOj7ryS84khybFpP_lTqzV7uV-T_m0cTfwvdn5BnBSKPxKgEb11",
_10
"token_type": "Bearer",
_10
"expires_in": 3600
_10
}

Request artist data

For this example, we will use the Get Artist endpoint to request information about an artist. According to the API Reference, the endpoint needs the Spotify ID of the artist.

An easy way to get the Spotify ID of an artist is using the Spotify Desktop App:

  1. Search the artist
  2. Click on the three dots icon from the artist profile
  3. Select Share > Copy link to artist. The Spotify ID is the value that comes right after the open.spotify.com/artist URI.

Our API call must include the access token we have just generated using the Authorization header as follows:


_10
curl "https://api.spotify.com/v1/artists/4Z8W4fKeB5YxbusRsdQVPb" \
_10
-H "Authorization: Bearer BQDBKJ5eo5jxbtpWjVOj7ryS84khybFpP_lTqzV7uV-T_m0cTfwvdn5BnBSKPxKgEb11"

If everything goes well, the API will return the following JSON response:


_40
{
_40
"external_urls": {
_40
"spotify": "https://open.spotify.com/artist/4Z8W4fKeB5YxbusRsdQVPb"
_40
},
_40
"followers": {
_40
"href": null,
_40
"total": 7625607
_40
},
_40
"genres": [
_40
"alternative rock",
_40
"art rock",
_40
"melancholia",
_40
"oxford indie",
_40
"permanent wave",
_40
"rock"
_40
],
_40
"href": "https://api.spotify.com/v1/artists/4Z8W4fKeB5YxbusRsdQVPb",
_40
"id": "4Z8W4fKeB5YxbusRsdQVPb",
_40
"images": [
_40
{
_40
"height": 640,
_40
"url": "https://i.scdn.co/image/ab6761610000e5eba03696716c9ee605006047fd",
_40
"width": 640
_40
},
_40
{
_40
"height": 320,
_40
"url": "https://i.scdn.co/image/ab67616100005174a03696716c9ee605006047fd",
_40
"width": 320
_40
},
_40
{
_40
"height": 160,
_40
"url": "https://i.scdn.co/image/ab6761610000f178a03696716c9ee605006047fd",
_40
"width": 160
_40
}
_40
],
_40
"name": "Radiohead",
_40
"popularity": 79,
_40
"type": "artist",
_40
"uri": "spotify:artist:4Z8W4fKeB5YxbusRsdQVPb"
_40
}

Congratulations! You made your first API call to the Spotify Web API.

Summary

  • The Spotify Web API provides different endpoints depending on the data we want to access. The API calls must include the Authorization header along with a valid access token.

  • This tutorial makes use of the client credentials grant type to retrieve the access token. That works fine in scenarios where you control the API call to Spotify, for example where your backend is connecting to the Web API. It will not work in cases where your app will connect on behalf of a specific user, for example when getting private playlist or profile data.

What's next?

  • The tutorial used the Spotify Desktop App to retrieve the Spotify ID of the artist. The ID can also be retrieved using the Search endpoint. An interesting exercise would be to extend the example with a new API call to the /search endpoint. Do you accept the challenge?

  • The authorization guide provides detailed information about which authorization flow suits you best. Make sure you read it first!

  • You can continue your journey by reading the API calls guide which describes in detail the Web API request and responses.

  • Finally, if you are looking for a more practical documentation, you can follow the Display your Spotify Profile Data in a Web App how-to which implements a step-by-step web application using authorization code flow to request the access token.