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 http://developer.echonest.com/api/v4/[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.
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 UTF-8 encoding when sending arguments to API methods.
Some API methods need to be authenticated. We use Oauth authentication for these requests. For these authenticated requests you must generate a cryptographic signature based upon your request, consumer key and shared secret. The authentication process can be a bit complicated, so it is recommended that you use a library (such as pyechonest or jEN) to handle all of the authentication details. To sign a request, you add a nonce parameter (a random string of characters that differs from call to call), a timestamp (the number of seconds since the epoch) and a signature which is generated by applying a cryptographic hash (such as SHA1) to your consumer key, shared secret and the base string portion of the request. A guide to signing requests can be found in The Oauth 1.0 Guide. Netflix also has an excellent description of how to sign requests in their Authentication oveview.
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 developer@echonest.com. 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 'http://developer.echonest.com/api/v4/artist/profile?api_key=N6E4NIOVYMTHNDM8J&name=weezer'
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.
Many calls take ID of items (artists, songs, tracks, etc). IDs can be full formed Echo Nest IDs like music://id.echonest.com/~/AR/ARC51DL1187B9A9FED or can in abbreviated form such as ARC51DL1187B9A9FED. We also support other ID spaces through Project Rosetta stone.
The Echo Nest API supports multiple ID spaces. You can use an ID from a supported ID space in place of an Echo Nest ID in any call that takes an Echo Nest ID. For example, you can get news for Radiohead using a Rdio ID like so:
http://developer.echonest.com/api/v4/artist/news?api_key=N6E4NIOVYMTHNDM8J&id=rdio-us-streaming:artist:r91318&format=json
Or using a 7Digital ID like so:
http://developer.echonest.com/api/v4/artist/news?api_key=N6E4NIOVYMTHNDM8J&id=7digital-US:artist:304&format=json
Similarly you can use a personal catalog foreign_id like so:
http://developer.echonest.com/api/v4/artist/news?api_key=N6E4NIOVYMTHNDM8J&id=CAXFDYO12E2688C130:artist:item-1&format=json
Methods that return Echo Nest IDs can also be used to retrieve IDs in a foreign ID space. For example, the following artist similarity call will return rdio artist IDs:
http://developer.echonest.com/api/v4/artist/similar?api_key=N6E4NIOVYMTHNDM8J&name=radiohead&format=json&bucket=id:rdio-us-streaming
Certain methods can be constrained to only return items that are members of the given ID space. For example, by setting the limit parameter to true, the following artist/similar call will limit results to those that fall in the 7Digital catalog:
http://developer.echonest.com/api/v4/artist/similar?api_key=N6E4NIOVYMTHNDM8J&name=radiohead&format=json&bucket=id:7digital-US&limit=true
Similarly, methods can be constrained to only return items that are members of a personal catalog. For example, the following call will limit similar artists to only those that are contained in the catalog CAABOUD13216257FC7:
http://developer.echonest.com/api/v4/artist/similar?api_key=N6E4NIOVYMTHNDM8J&name=radiohead&format=json&bucket=id:CAABOUD13216257FC7&limit=true
These parameters are valid for all methods in the API
Parameter Required? Multiple? Values Description api_key yes no N6E4NIOVYMTHNDM8J 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
| 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 |