Genre API Methods

Api calls for getting data about genres.

The Echo Nest provides methods to return data about a wide range of music genres.

Buckets: Some genre methods such as list, similar and profile accept a bucket parameter. This parameter allows you to specify what additional data should be returned with each genre. Multiple buckets can be specified simultaneously allowing you to request multiple sets of data in a single call. Possible genre buckets are:

Bucket Description
Description A short description of the genre
urls Links to this genre's pages on various sites

artists

Return the top artists for the given genre

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
name yes no afrobeat, acid jazz the genre name
bucket no yes biographies, blogs, discovery, discovery_rank, doc_counts, familiarity, familiarity_rank, genre, hotttnesss, hotttnesss_rank, images, artist_location, news, reviews, songs, terms, urls, video, years_active, id:Rosetta-space indicates what data should be returned with each artist
limit no no true, false if true artists will be limited to those that appear in any of the catalogs specified by the id: bucket

Warning

If limit is set to true, at least one idspace must also be provided in the bucket parameter.

Bucket: When specifying idspace buckets (those starting with "id:") the results will be returned in a "foreign_ids" key/element.

Example query:

http://developer.echonest.com/api/v4/genre/artists?api_key=YOUR_API_KEY&format=json&results=5&start=0&bucket=hotttnesss&name=jazz

Here is an example response:

{
    "response": {
        "artists": [
            {
                "hotttnesss": 0.601159,
                "id": "AR9PLH11187FB58A87",
                "name": "Thelonious Monk"
            },
            {
                "hotttnesss": 0.598763,
                "id": "ARIOZCU1187FB3A3DC",
                "name": "John Coltrane"
            },
            {
                "hotttnesss": 0.612279,
                "id": "ARJ6VQ21187B98BC8A",
                "name": "Charles Mingus"
            },
            {
                "hotttnesss": 0.520978,
                "id": "ART95BW1187FB3AF79",
                "name": "Yusef Lateef"
            },
            {
                "hotttnesss": 0.657461,
                "id": "AR7RTGF1187FB38793",
                "name": "Miles Davis"
            }
        ],
        "status": {
            "code": 0,
            "message": "Success",
            "version": "4.2"
        }
    }
}

list

Returns a list of all of the available genres.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
bucket no yes description, urls indicates what data should be returned with each genre

Example query:

http://developer.echonest.com/api/v4/genre/list?api_key=YOUR_API_KEY&format=json&results=5

Here is an example response:

{
    "response": {
        "genres": [
            {
                "name": "a cappella"
            },
            {
                "name": "abstract hip hop"
            },
            {
                "name": "acid house"
            },
            {
                "name": "acid jazz"
            },
            {
                "name": "acid techno"
            }
        ],
        "start": 0,
        "status": {
            "code": 0,
            "message": "Success",
            "version": "4.2"
        },
        "total": 777
    }
}

profile

Get basic information about a genre.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
name yes no afrobeat, acid jazz the genre name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
bucket no yes description, urls indicates what data should be returned with each genre

Example queries:

http://developer.echonest.com/api/v4/genre/profile?api_key=YOUR_API_KEY&name=acid+jazz&bucket=description&bucket=urls

Here is an example response:

{
    "response": {
        "genres": [
            {
                "description": "Acid jazz, also called club jazz, is a style of jazz that takes cues from a number of genres, including funk,
hip-hop, house, and soul.",
                "name": "acid jazz",
                "urls": {
                    "wikipedia_url": "http://en.wikipedia.org/wiki/Acid_jazz"
                }
            }
        ],
        "status": {
            "code": 0,
            "message": "Success",
            "version": "4.2"
        }
    }
}

similar

Return similar genres to a given genre.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
name no no afrobeat, acid jazz the genre name
results no no 0 < results < 100, (default=100) the number of results desired
start no no 0, 15, 30 the desired index of the first result returned
bucket no yes description, urls indicates what data should be returned with each genre

Example queries:

http://developer.echonest.com/api/v4/genre/similar?api_key=YOUR_API_KEY&name=acid+jazz&bucket=description

Here is an example response:

{
    "response": {
        "genres": [
            {
                "name": "rock",
                "similarity": 0.768293
            },
            {
                "name": "hard rock",
                "similarity": 0.539634
            },
            {
                "name": "classic rock",
                "similarity": 0.47561
            },
            {
                "name": "mellow gold",
                "similarity": 0.460366
            },
            {
                "name": "glam rock",
                "similarity": 0.362805
            }
        ],
        "start": 0,
        "status": {
            "code": 0,
            "message": "Success",
            "version": "4.2"
        },
        "total": 19
    }
}