Understanding API method responses

This tutorial gives describes the various types of responses you can get from our API calls

Response formats

The Echo Nest APIs returned data in a number of formats. XML, JSON, JSONP. The format of the response is set by the format parameter. The default format is JSON. Here's a response for a simple artist hotttnesss query.

JSON Example

JSON Response

{
    "response": {
        "artist": {
            "hotttnesss": 1.0, 
            "id": "ARX6TAQ11C8A415850", 
            "name": "Lady Gaga"
        }, 
        "status": {
            "code": 0, 
            "message": "Success", 
            "version": "4.2"
        }
    }
}

XML Example

Here and an example of the same call with an XML response

XML Response

    <response>
        <status>
            <version>4.2<version>
            <code>0<code>
            <message>Success<message>
        <status>
        <artist>
            <hotttnesss>1.0<hotttnesss>
            <id>ARX6TAQ11C8A415850<id>
            <name>Lady Gaga<name>
        <artist>
    <response>

JSONP Example

JSONP is a variant of JSON that allows you to get around the single source restrictions of JSON and XML. With JSONP you can create web apps that use the Echo Nest APIs directly, with no need for you to create your own server. If you set the format to JSONP you must also set a callback parameter.

JSONP Response

myJsonpCallback(
{
    "response": {
        "artist": {
            "hotttnesss": 1.0, 
            "id": "ARX6TAQ11C8A415850", 
            "name": "Lady Gaga"
        }, 
        "status": {
            "code": 0, 
            "message": "Success", 
            "version": "4.2"
        }
    }
})

The response element

The API response is a dictionary with a 'response' element that contains a 'status' element as well as a payload element with the requested data (in this case the playload element is 'artist'). The 'status' element includes error code and and message fields that describe any errors that may have occurred when processing the request. See the section on response codes for a detailed description of the various types of codes.

Error Example

Here is an example of an error response

Response

{
    "response": {
        "status": {
            "code": 2, 
            "message": "api_key - API key not allowed: \"BAD_API_KEY\" is not allowed to call this method", 
            "version": "4.2"
        }
    }
}


HTTP Status codes

The API will set HTTP status codes as appropriate (see the w3 spec for gory details on codes). The most frequent HTTP status codes returned by the API are
  • 200 - All is well
  • 400 - Bad request - typically this occurs when a bad parameter is given to a method
  • 500 - Internal Server Error - the request is valid but an error occurred while trying to serve the request. We work hard to make sure that these never happen but sometimes they do.

Response notes

If you are parsing the response, keep these points in mind to make sure that your parsing will be future proof.
  • We don't have every piece of data for every artist or song, so make sure you handle missing items gracefully.
  • We may add new fields to a response as we incorporate new data into our system, so make sure you can handle unexpected items gracefully.
  • Don't rely on the order of fields in a response.