Response format

Currently, XML is the only response format available, but in order to make sure that you’ll continue to receive XML when we add more formats, it may be a good idea to specify that you want XML anyway.

There are two ways of negotiating response formats. The preferred way is using the Accept header. In cases where you have no control of the headers sent, you can also use the url to specify response format. In order to do this, append a format extension to the end of the API method. A table of available formats can be found below.

In order to search for “true affection”, and get XML back, you can either do

GET /search/1/track?q=true+affection HTTP/1.1
Accept: application/xml

or, the format extension way

GET /search/1/track.xml?q=true+affection HTTP/1.1

Available formats

Requesting an unavailable format with content negotiation will result in a 406 Not Acceptable error. Specifying an unavailable format in the url will result in a 404 Not Found.

Territory restrictions

Albums and tracks in Spotify are subject to territorial restrictions. The APIs expose in which country each album and track may be played. In the album element (of album and track search), there is an element called availability. Inside it, there is an element territories. It contains a list of the ISO 3166-1 alpha-2 country codes in which the album is available. The value may also be the special string “worldwide”, indicating that the album can be played anywhere.

Example:

<?xml version="1.0" encoding="utf-8"?>
<tracks xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns="http://www.spotify.com/ns/music/1">
  <opensearch:Query role="request" startPage="1" searchTerms="lykke li"/>
  <opensearch:totalResults>117</opensearch:totalResults>
  <opensearch:startIndex>0</opensearch:startIndex>
  <opensearch:itemsPerPage>100</opensearch:itemsPerPage>
  <track href="spotify:track:6PZDPg3dZgJkNL6nVMUB4b">
    <name>Little Bit</name>
    <artist href="spotify:artist:6oBm8HB0yfrIc9IHbxs6in">
      <name>Lykke Li</name>
    </artist>
    <album href="spotify:album:6zBW3pmU291VbFHq4EdU8C">
      <name>Youth Novels</name>
      <released>2008</released>
      <availability>
        <territories>FI NO SE</territories>
      </availability>
      ...

If you know in which country the user of your application lives, and this is outside of Finland, Norway and Sweden, you may want to indicate that this track will not be playable.

Caching

Most API responses come with the Last-Modified and Expires HTTP headers set. These can be used for client-side cache control. If you have a response cache, don’t request again until the response has expired, and whenever you do request something again, set the If-Modified-Since request header to the last Last-Modified value returned. If the response hasn’t changed, 304 Not Modified is returned.

If you first request

GET /search/1/track?q=i+turn+my+camera+on HTTP/1.1

HTTP/1.1 200 OK
Last-Modified: Wed, 06 May 2009 07:45:56 GMT

<?xml version="1.0" encoding="utf-8"?>
...

And then

GET /search/1/track?q=i+turn+my+camera+on HTTP/1.1
If-Modified-Since: Wed, 06 May 2009 07:45:56 GMT

HTTP/1.1 304 Not Modified
...

Rate limiting

In order to make the Metadata API snappy and open for everyone to use, rate limiting rules apply. If you make too many requests too fast, you’ll start getting 403 Forbidden responses. When rate limiting has kicked in, you’ll have to wait 10 seconds before making more requests.

The rate limit is currently 10 request per second per ip. This may change.

Comments? Feedback?

Welcome to report bugs, give feedback or ask questions in the blog post announcing the metadata API.