Echo Nest API Overview

This document describes The Echo Nest API v4. For v3 docs, go here.

Overview

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. The API root URL is located at http://developer.echonest.com/api/

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.

Keys

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 APIs; 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 APIs.

• 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 developer@echonest.com.
• 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 APIs for commercial use. - The Echo Nest's APIs are for non-commercial purposes only. If you are a lone developer selling advertising that is barely covering your running costs, we consider that non-commercial. If you are are a company writing paychecks, making plenty of money or driving a venture-capital-purchased MacBook Pro, you're probably commercial. Again, we want to be flexible and support many uses of the platform, so just contact us at developer@echonest.com if you have any questions about whether your use is commercial.
• Credit. - Please give us due credit when using the Echo Nest API. Display an Echo Nest logo available on the logos page along with a link to http://the.echonest.com/ when displaying content provided by the APIs.
• Don't do anything illegal. - Don't use the API 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 access to the API 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 APIs and make a copy of our data to steal our mojo.
• Help us manage server and bandwidth costs. - Don't use the API in a manner that exceeds reasonable request volume, or constitutes excessive or abusive usage as determined by The Echo Nest.

Encoding

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

Identifiers

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.

Currently supported ID spaces are:

• musicbrainz artists - Example: musicbrainz:artist:a74b1b7f-71a5-4011-9441-d0b5e4122711
• 7Digital artists - Example: 7digital:artist:341546 or 7digital:artist:341546
• Playme artists - Example: playme:artist:1234

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

Resources

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

Discussion

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