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
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. See Project Rosetta Stone for more information on ID spaces.
Example query:
http://developer.echonest.com/api/v4/genre/artists?api_key=YOUR_API_KEY&format=json&results=5&start=0&bucket=hotttnesss&name=jazzHere 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" } } }
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=5Here 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 } }
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=urlsHere 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" } } }
Search for genres by name
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 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 name no no blues, rock the genre substring to search for Example query:
http://developer.echonest.com/api/v4/genre/search?api_key=YOUR_API_KEY&format=json&name=rock&results=5Here 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 } }
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=descriptionHere 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 } }
