Echo Nest API Overview

Important API Announcement, March 29th 2016

We’re always working to make improvements to our Web APIs and today, we have some updates to share that will impact both The Spotify and The Echo Nest Web APIs.

Over the past two years, following Spotify’s acquisition of The Echo Nest, it’s become clear that rather than have two separate APIs with considerable overlap in features, it makes sense to migrate functionality and focus all of our future development on the Spotify API.

In doing so, there are a couple important dates you should be aware of:

  1. March 29th, 2016 - As of today, We are announcing three new APIs (details below) and The Echo Nest API will no longer be issuing new API keys
  2. May 31, 2016 - As of May 31st, The Echo Nest platform will no longer serve requests and developers will need to move over to the Spotify API.

As part of our migration of many of The Echo Nest API features over to the Spotify Web API, we’re announcing three new APIs today. The new Spotify Web APIs include:

  1. Audio Features - Access to audio information about tracks (energy, danceability, tempo, loudness, etc. as well as full detailed audio analysis)
  2. Recommendations - A recommendation API (to generate a list of tracks given a starting point from a seed artist, track or genre), with filtering capabilities to restrict the set of tracks that are returned.
  3. User's Top Artists, Tracks - Top-level user information such as top artists and tracks.

If you currently have an app that uses The Echo Nest API, check out the Spotify Web API as we’ve already migrated the most-used features.

As always, we’ll continue to add additional features and enhancements to ensure you have what you need for development.

For more information on these new APIs check out the details on the Spotify Blog.


The Echo Nest API allows you to call methods that respond in JSON or XML. Individual methods are detailed in the menu on the left. You can call a method by using an HTTP GET to retrieve[type]/[method] along with method specific arguments.


You must have your own API key to make use of The Echo Nest API. To obtain a key, register for an account.

The example method calls in this set of documentation use a guest API key that is for demonstration purposes only and should not be used for any other application.

Ground Rules

We want to be as flexible as possible with our API and data feeds; if you have an interesting use of our platform, we want to help. Here are some basic ground rules that all developers should abide by when using the API and data feeds.

  • Use common sense. If you're unsure, ask us. - Our terms of service allow for most reasonable non-commercial uses. If you're doing something you think might be a problem or if you have any questions, just contact us at
  • Read the Terms of Service. - Before you start developing anything using the Echo Nest API, you need to read and abide by the full Terms of Service.
  • Do not use the API or feeds for commercial use without talking to us. - The Echo Nest's API is free for non-commercial purposes. To use them commercially, talk to us and we will go over the licensing options. In either case, we request that you give us proper branding and attribution when using our data. If you are a lone developer selling advertising that is barely covering your running costs, we consider that non-commercial. If you are a company writing paychecks, making plenty of money or driving a venture-capital-purchased MacBook Pro, you're probably commercial. For commercial use, we have standard terms & conditions that we can share with you. We want to be flexible and support many uses of the platform, so just contact us at if you have any questions about whether your use is commercial.
  • Credit. - Please give us due credit when using the Echo Nest API and feeds. Display an Echo Nest logo available on the logos page along with a link to when displaying content provided by the API or feeds.
  • Don't do anything illegal. - Don't use the API or feeds in connection with anything that promotes or takes part in any products, services, or materials that we would consider malicious, hateful, or illegal.
  • Don't pretend the data is yours. - You may not sell, lease, share, transfer, or sublicense the API or feeds or access to the API/feeds to any other party than the API key holder. You can cache our data to lighten bandwidth and improve latency, but don't crawl/spider our API or data feeds and make a copy of our data to steal our mojo.
  • Help us manage server and bandwidth costs. - Don't use the API or feeds in a manner that exceeds reasonable request volume, or constitutes excessive or abusive usage as determined by The Echo Nest. Don't register for multiple API keys in an attempt to cirumvent rate limits.


Use UTF-8 encoding when sending arguments to API methods.

Rate Limits

API methods are subject to rate limits. In general, non-commercial users of our API can expect a rate limit of around 120 calls per minute. This may vary depending upon overall system activity. If we are under a light load we may increase the limit associated with your API key and conversely, if we are under heavy load we may reduce that limit. If you need a guaranteed API limit, contact us at You can discover what your current rate limit and activity is by inspecting the response header that is returned with each API method call. There are three fields in the header associated with rate limits:

  • X-RateLimit-Limit - the current rate limit for this API key
  • X-RateLimit-Used - the number of method calls used on this API key this minute
  • X-RateLimit-Remaining - the estimated number of remaining calls allowed by this API key this minute

You can inspect the response header with the -i option to curl like so:

curl -i ''

This returns a response header with content like so:

HTTP/1.1 200 OK
Content-Length: 135
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 62
X-RateLimit-Used: 58

This indicates that the current rate limit is 120 calls per minute. In the current minute 58 calls have been made and we estimate that you will have 62 calls remaining for the current minute.

If you exceed the rate limit during a period, API methods will fail with an HTTP response status code of 429.


Many calls take ID of items (artists, songs, tracks, etc). IDs can be full formed Echo Nest IDs like music:// or can in abbreviated form such as ARC51DL1187B9A9FED.

Standard Parameters

These parameters are valid for all methods in the API

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
format no no json, jsonp, xml the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests

Response Codes

Code Value
-1 Unknown Error
0 Success
1 Missing/ Invalid API Key
2 This API key is not allowed to call this method
3 Rate Limit Exceeded
4 Missing Parameter
5 Invalid Parameter

HTTP Response Codes

The HTTP Status response status code can be used to determine the status of an API request:

  • 200 - Success
  • 304 - Not Modified - indicates that the resource has not been modified since the version specified by the request headers If-Modified-Since or If-Match.
  • 400 - Bad Request - the request is not valid
  • 403 - Forbidden - you are not authorized to access that resource
  • 404 - Not Found - The requested resource could not be found
  • 429 - Too Many Requests - You have exceeded the rate limit associated with your API key
  • 5XX - Server Error - The Echo Nest is having an internal issue and cannot serve your request


Visit our downloads for links to existing Echo Nest API-related code.


Join our forums to provide feedback and discuss development with other developers.