Web API

Based on simple REST principles, the Spotify Web API endpoints return JSON metadata about music artists, albums, and tracks, directly from the Spotify Data Catalogue.

Web API also provides access to user related data, like playlists and music that the user saves in the Your Music library. Such access is enabled through selective authorization, by the user.

The base address of Web API is https://api.spotify.com. The API provides a set of endpoints, each with its own unique path. To access private data through the Web API, such as user profiles and playlists, an application must get the user’s permission to access the data. Authorization is via the Spotify Accounts service.

Requests

The Spotify Web API is based on REST principles. Data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. Where possible, Web API uses appropriate HTTP verbs for each action:

Spotify URIs and IDs

In requests to the Web API and responses from it, you will frequently encounter the following parameters:

Responses

Web API responses normally include a JSON object. Browse the reference documentation to find descriptions of common responses from each endpoint.

Timestamps

Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ. If the time is imprecise (for example, the date/time of an album release), an additional field indicates the precision; see for example, release_date in an album object.

Pagination

Some endpoints support a way of paging the dataset, taking an offset and limit as query parameters:

$ curl
https://api.spotify.com/v1/artists/1vCWHaC5f2uS3yhpwWbIA6/albums?album_type=SINGLE&offset=20&limit=10

In this example, in a list of 50 (total) singles by the specified artist : From the twentieth (offset) single, retrieve the next 10 (limit) singles.

Conditional Requests

Most API responses contain appropriate cache-control headers set to assist in client-side caching:

• If you have cached a response, do not request it again until the response has expired.
• If the response contains an ETag, set the If-None-Match request header to the ETag value.
• If the response has not changed, the Spotify service responds quickly with 304 Not Modified status, meaning that your cached version is still good and your application should use it.

Response Status Codes

Web API uses the following response status codes, as defined in the RFC 2616 and RFC 6585:

Response Schema

Web API uses two different formats to describe an error:

• Authentication Error Object
• Regular Error Object

Authentication Error Object

Whenever the application makes requests related to authentication or authorization to Web API, such as retrieving an access token or refreshing an access token, the error response follows RFC 6749 on the OAuth 2.0 Authorization Framework.

Here is an example of a failing request to refresh an access token.

$ curl -H "Authorization: Basic Yjc...cK" -d grant_type=refresh_token -d refresh_token=AQD...f0 "https://accounts.spotify.com/api/token"

{
    "error": "invalid_client",
    "error_description": "Invalid client secret"
}

Regular Error Object

Apart from the response code, unsuccessful responses return a JSON object containing the following information:

Here, for example is the error that occurs when trying to fetch information for a non-existent track:

$ curl -i "https://api.spotify.com/v1/tracks/2KrxsD86ARO5beq7Q0Drfqa"

HTTP/1.1 400 Bad Request
{
    "error": {
        "status": 400,
        "message": "invalid id"
    }
}

Authentication

All requests to Web API require authentication. This is achieved by sending a valid OAuth access token in the request header. For more information about these authentication methods, see the Web API Authorization Guide.