Our Web API provides client applications with fast and reliable access to Spotify data.

Note that by using Spotify developer tools, you accept our Developer Terms of Use.

About the Web API

Through the Spotify Web API your applications can retrieve and manage Spotify content. The base address of the API is https://api.spotify.com. There are several endpoints at that address, each with its own unique path. Many endpoints are open and your do not need any special permissions to access them. 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 at https://accounts.spotify.com.

Note: Our Metadata API is now deprecated. All its functionality is found in the new Web API. For now, the Metadata API endpoints are available, but be aware they will be removed in the near future. We recommend you migrate your existing applications to the Web API as soon as possible.

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, the API strives to use appropriate HTTP verbs for each action:

Verb
Description
GET
Used for retrieving resources.
POST
Used for creating resources.
PUT
Used for changing/replacing resources or collections.
DELETE
Used for deleting resources.

Spotify URIs and IDs

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

Parameter
Description
Example
Spotify URIThe resource identifier that you can enter, for example, in the Spotify Desktop client's search box to locate an artist, album, or track. To find a Spotify URI simply right-click (on Windows) or Ctrl-Click (on a Mac) on the artist's or album's or track's name.spotify:track:6rqhFgbbKwnb9MLmUQDhG6
Spotify IDThe base-62 identifier that you can find at the end of the Spotify URI (see above) for an artist, track, album, playlist, etc. Unlike a Spotify URI, a Spotify ID does not clearly identify the type of resource; that information is provided elsewhere in the call.6rqhFgbbKwnb9MLmUQDhG6
Spotify category IDThe unique string identifying the Spotify category that you can find at the end of the Spotify URI for the category. party
Spotify user IDThe unique string identifying the Spotify user that you can find at the end of the Spotify URI for the user. The ID of the current user can be obtained via the Web API endpoint https://api.spotify.com/v1/me.wizzler
Spotify URLAn HTML link that opens a track, album, app, playlist or other Spotify resource in a Spotify client (which client is determined by the user's device and account settings at play.spotify.com).http://open.spotify.com/track/6rqhFgbbKwnb9MLmUQDhG6

Rate limiting

To make the API fast for everybody, rate limits apply. Unauthenticated requests are processed at the lowest rate limit. Authenticated requests with a valid access token benefit from higher rate limits — this is true even if endpoint doesn’t require an access token to be passed in the call. Read the Authorization Guide for more information about how to register an application and sign your requests with an access token.

A way to reduce the amount of requests is to use endpoints that fetch multiple entities. If you are making many requests to get single tracks, albums or artists, you can use endpoints such as Get Several Tracks, Get Several Albums or Get Several Artists instead.

Responses

All data is received as a JSON object. The Web API Object Model provides a description of all the retrievable objects.

Timestamps

Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with zero offset: YYYY-MM-DDTHH:MM:SSZ. If the time is imprecise (for example, the date/time of an album release), an additional field will show 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"

Note that offset numbering is zero-based and that omitting the offset parameter will return the first X elements. Check the documentation for the specific endpoint to see the default limit value. Requests that return an array of items are automatically paginated if the number of items vary (for example, tracks in a playlist). In this case, the results are returned within a paging object.

Conditional requests

Most API responses come with appropriate cache-control headers set to assist in client-side caching. If you have cached a response, do not request 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 hasn’t changed, the Spotify service will respond quickly with the 304 Not Modified status (i.e., your cached version is still good and your application should use it).

Some playlist endpoints also return a snapshot-id. This enables you to target your changes to a particular historical version of a playlist and have those changes rolled through to the latest version: see Working With Playlists.

Response Status Codes

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

Status Code
Description
200
OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.
201
Created - The request has been fulfilled and resulted in a new resource being created.
204
No Content - The request has succeeded but returns no message body.
304
Not Modified. See Conditional requests.
400Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information; see Error Details, below.
401
Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.
403
Forbidden - The server understood the request, but is refusing to fulfill it
404
Not Found - The requested resource could not be found. This error can be due to a temporary or permanent condition.
429Too Many Requests - Rate limiting has been applied.
500Internal Server Error. You should never receive this error because our clever coders catch them all ... but if you are unlucky enough to get one, please it to us as a comment at the bottom of this page.
502
Bad Gateway - The server was acting as a gateway or proxy and received an invalid response from the upstream server.
503
Service Unavailable - The server is currently unable to handle the request due to a temporary condition which will be alleviated after some delay. You can choose to resend the request again.

Error Details

The API uses two different formats to describe an error.

Authentication error object

Whenever the application makes requests to the API which are related to authentication or authorization, e.g. retrieving an access token or refreshing an access token, the error response follows RFC 6749 on The OAuth 2.0 Authorization Framework.

Key
Value Type Value Description
errorstringA high level description of the error as specified in RFC 6749 Section 5.2.
error_description stringA more detailed description of the error as specified in RFC 6749 Section 4.1.2.1.
Below 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 information about the error as an error JSON object containing the following information:

Key
Value Type Value Description
status
integerThe HTTP status code (also returned in the response header; see Response Status Codes for more information).
message
stringA short description of the cause of the error.
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

Some requests to the 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. Note that, to access a user’s personal information, you need an access token generated by asking the user permission to access the data.

Integration with Echo Nest

Because the Spotify Web API is based on REST principles it will play nicely with any other APIs to help you build world-class music apps. In particular you should check out the Echo Nest API. The Echo Nest offers a wide array of music data and services. Hundreds of music applications already tap into The Echo Nest API for access to billions of data points about music from leading media companies (MTV, the BBC, MOG, and others) to award-winning mobile applications (Discovr, Music Hunter, Pocket Hipster).

The Echo Nest’s Rosetta Stone project supports multiple ID spaces including, of course, Spotify IDs. This opens up a wide range of applications that make use of data from both services. For example, you can pass a Spotify artist ID to the Echo Nest API and get back latest news about the artist. Here is an example for the artist 5l8VQNuIg0turYE1VtM9zV (Leonard Cohen):

http://developer.echonest.com/api/v4/artist/news?api_key={echonest_api_key}&id=spotify:artist:5l8VQNuIg0turYE1VtM9zV&format=json

You will need to register for an Echo Nest key to use in your calls. More information can be found on the Echo Nest / Spotify API Sandbox page.