API calls for managing taste profiles
The Taste Profile API allows for the managing of application-specific taste profiles. A taste profile is a named collection of music items (artists, songs) that can be used as input to other API calls. Note that here at the Echo Nest we use the terms 'taste profile' and 'catalog' interchangeably. All taste profile methods are invoked via the 'catalog' prefix.
Some example use cases:
- Personal playlisting - the songs returned in a playlist by the Playlist API can be constrained to the songs in a taste profile associated with a user.
- Event recommendation - a taste profile can be created for a festival that contains all the artists in the festival. Music recommendations can be constrained to artists in the taste profile.
- Personalized recommendation - the contents of a taste profile can be used to represent an individual's taste and given as a seed to artist/similar calls.
- Bulk resolution - a user application can quickly resolve taste profile items to Echo Nest IDs and then retrieve info such as song tempo for a large catalog of items.
- User-to-user recommendation - users with similar tastes can be discovered with the catalog/similar call
Methods that support rosetta stone ID spaces, such as artist/similar, playlist, and song/search, can be given a taste profile to restrict the results to a given taste profile. This makes it possible to limit results to an indvidual's music collection.
You can also use taste profile foreign IDs as rosetta IDs for songs and artists in place of Echo Nest IDs throughout the APIs: CAOFUDS12BB066268E:artist:kfw or CAGPXKK12BB06F9DE9:song:0CF07A178DBF78F7
A taste profile can have up to 100,000 items in it. A non-commercial API key can have 1,000 taste profiles associated with it.
Taste Profiles are typed; a taste profile can be an 'artist' taste profile a 'song' taste profile or a 'general' taste profile. An 'artist' taste profile can contain only artists. A 'song' taste profile can contain only songs. A 'general' taste profile can contain artists and songs.
Taste Profile key/value store Each taste profile has a key/value store associated with it that can be used to store application-specific information in the taste profile. The key/value store can be used to help filter results. For instance, an application may have taste profiles associated with users and with radio stations. This type information can be represented by a 'type' key. User taste profiles can be given a type of 'user' and radio station profiles a type of 'station'. A radio station recommendation for a user can then be created by finding taste profiles with a type of 'station' that are most similar to the user's taste profile. You can add/update and delete key/values via the catalog/update method. The values of the key/value store for a taste profile can be retrieved via the catalog/keyvalues method.
The Per-item custom attributes Each item in a taste profile can be associated with a set of custom attributes. These custom attributes are name/value pairs. There can be up to 20 custom attributes per item. Attribute names are short strings (maximum length of 32 characters). Attribute values are strings, numbers or lists of strings.
Taste Profile Attributes (Alpha)
We are providing a set of taste profile summary attributes that should make it easier to understand a music fan. Here are the attributes we’re making available to start:
- Diversity - measures the overall diversity of a fan’s listening by mapping the overall distance across the musical styles of the listener.
- Mainstreamness - measures the overall familiarity of a user’s listening activity to determine preference for either mainstream or more obscure music.
- Freshness - measures listening habits to determine how much a user cares about new album releases vs. sticking with older music
- Adventurouness - measures how open the listener is to music outside of his or her musical comfort zone.
The Taste Profile Attributes are currently in alpha release.
The Resolving Process
The catalog/update method allows for items (artists, songs) to be added to a taste profile. When such an update is made, the Echo Nest will attempt to resolve the updated items to Echo Nest IDs. This resolution process happens asynchronously since it can take some time for large taste profiles. The update method returns a 'ticket' that can be used to check the status of the taste profile update.
The resolution process involves taking whatever information is provided for an item (artist name, release name, song name, etc) and attempting to resolve it to an Echo Nest ID.
Creates a taste profile.
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests name yes no Paul's favorite artists The name of the taste profile type yes no artist, song, general The type of the taste profile Warning
This method requires an HTTP Post request.
Example post:
curl -F "api_key=YOUR_API_KEY" -F "format=json" -F "type=artist" -F "name=test_artist_catalog" "http://developer.echonest.com/api/v4/catalog/create"Here is an example response:
{ "response": { "status": { "code": 0, "message": "Success", "version": "4.2" }, "name": "test_artist_catalog", "id": "CAOFUDS12BB066268E" "type": "artist", } }
Updates (adds or deletes) items from a taste profile. The body of the post should include an item block that describes modifications to the taste profile.
When a taste profile is updated, the contents of the taste profile are resolved to Echo Nest IDs. This resolving process happens asynchronously to the call. The update method returns a 'ticket' that can be used with the catalog/status call to check on the status of the update.
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key. Only the API key that created a taste profile can update it format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests id yes no CANVFPJ131839D8144 The ID of the taste profile data_type no no json The type of data to be uploaded data yes no data in the form specified by 'data_type' The data to be uploaded Warning
This method requires an HTTP Post request
Example post:
curl -X POST "http://developer.echonest.com/api/v4/catalog/update" -F "api_key=YOUR_API_KEY" -F "data_type=json" -F "format=json" -F "id=CAJTFEO131216286ED" -F "data=@data_file.json"The format for the json item block for song or general taste profiles is of the form:
[ { "action":action code. one of ("delete","update","play","skip". Default is "update") "item": { "item_id":any identifier as long as hash(catalog_id+item_id) is unique. [REQUIRED] "track_id": rosetta ID OR ENID [OPTIONAL] "song_id": rosetta ID OR ENID [OPTIONAL] "song_name": song name [OPTIONAL] (song_name, song_id and track_id are mutually exclusive) // artist info should not be specified if a song_id or track_id is given "artist_id":rosetta ID OR ENID [OPTIONAL] "artist_name":artist name [OPTIONAL] (artist_name and artist_id are mutually exclusive) "release":name of release [OPTIONAL] "genre":name of genre [OPTIONAL] "track_number":integer [OPTIONAL] "disc_number":integer [OPTIONAL] "url":string of local filename or remote url [OPTIONAL] "favorite":bool true/false [OPTIONAL] "banned": bool true/false [OPTIONAL] "play_count":integer [OPTIONAL] "skip_count":integer [OPTIONAL] "rating":integer 0..10 [OPTIONAL] "item_keyvalues": { "class" : ["Primary", "Gold", "Deep Track"], "sound" : ["female", "disco", "pop"], "mood" : "upbeat", "rating" : 10, "tempo" : ["fast", "fast"] // starts fast, ends fast } } } ]
custom item attributes - Each item in a taste profile can associated with a set of custom attributes. These attributes can be retrieved by the 'item_keyvalues' bucket of the catalog/read method. Custom attributes are key/value pairs. Key names can be any ASCII string (limited to 32 chacters). There can be a maximum of 32 key/values per item. Values can be strings (up to 64 characters long), ints, or lists of strings.
Updating the catalog key/value store A taste profile can have an application specific key/value store. Key names can be any ASCII string (limited to 32 characters). Key values are strings (utf-8, limited to 64 characters each). There can be a maximum of 255 keys per taste profile. taste profile methods that return lists of taste profiles (such as catalog/similar) can be constrained to return only taste profiles that match a given set of key/value pairs.
To add key/values to the key/value store, issue a catalog/update request that includes an action of 'update' and includes a 'catalog_keyvalues' element that contains a dictionary of the key/value pairs to update. New keys will be added to the taste profile, existing keys will be updated with new values, keys with a value of null will be removed from the taste profile.
The 'catalog_keyvalues' element is in the following format:
catalog_keyvalues: { key1 : "value1", key2 : "value2", key3 : "3" }For example, here is the json update block to add a catalog_keyvalues block for a station taste profile:
[ { "action":"update", "catalog_keyvalues": { "type": "station", "format": "classic rock", "call-letters": "WGIR", "zipcode": "03101" } } ]Here is the json update block to add a catalog_keyvalues block for a user taste profile:
[ { "action":"update", "catalog_keyvalues": { "type": "user", "gender": "male", "yob": "1959", "zipcode": "03101" } } ]Here is the json update block to modify the zipcode and delete the "yob":
[ { "action":"update", "catalog_keyvalues": { "yob": null, "zipcode": "03103" } } ]item_id format - Note that the item_id will be hashed with the taste profile ID and the taste profile type to create a foreign_id that can be used in lieu of an Echo Nest ID. The item_id should be restricted to characters A-Z,a-z,0-9, ".", "_", "-".
Actions
Possible actions are:
- delete - the particular item is deleted
- update - the particular item is updated with the given info
The following are convenience actions; only the 'item_id' should be included in the item block for these actions:
- play - the play count of the particular item is incremented.
- skip - the skip count of the particular item is incremented.
An example of a json block used to create a new song or general taste profile:
[ { "item": { "item_id": "0CF07A178DBF78F7", "song_name" : "Harmonice Mundi II", "artist_name" : "Six Organs Of Admittance", "play_count" : 4 } }, { "item": { "item_id": "DBC4B9395930FB4A", "song_name" : "Spine", "artist_name" : "Gem Club", "favorite" : true } }, { "item": { "item_id": "2EC046EA14A873F8", "play_count" : 10 } }, ]An example update song block:
[ { "action": "update" "item": { "item_id": "0CF07A178DBF78F7", "rating": 7 } }, { "action": "update" "item": { "item_id": "DBC4B9395930FB4A", "favorite": false } }, { "action": "play" "item": { "item_id": "2EC046EA14A873F8", } }, { "action": "delete" "item": { "item_id": "015F873871C22D02", } }, ]The format for the json item block for artist and general taste profiles is of the form:
[ { "action":action code. one of ("delete","update","play","skip". Default is "update") "item": { "item_id":any identifier as long as hash(catalog_id+item_id) is unique. [REQUIRED] "artist_id":rosetta ID OR ENID [OPTIONAL] "artist_name":artist name [OPTIONAL] (artist_name and artist_id are mutually exclusive) "favorite":bool true/false [OPTIONAL] "banned": bool true/false [OPTIONAL] "play_count":integer [OPTIONAL] "skip_count":integer [OPTIONAL] "rating":integer 0..10 [OPTIONAL] } } ]Possible operations are:
- delete - the particular item is deleted
- update - the particular item is updated with the given info
The following are convenience actions, only the 'item_id' should be included in the item block for these actions:
- play - the play count of the particular item is incremented.
- skip - the skip count of the particular item is incremented.
An example of a json block used to create a new artist or general taste profile:
[ { "item": { "item_id": "itsgucci", "artist_name" : "Gucci Mane", } } { "item": { "item_id": "royk", "artist_name" : "Royksopp", "favorite" : true } }, { "item": { "item_id": "kfw", "artist_name" : "Keith Fullerton Whitman", } }, { "item": { "item_id": "cale", "artist_name" : "John Cale", } } ]An example update of an artist block:
[ { "action": "update" "item": { "item_id": "cale", "play_count": 504 } }, { "action": "update" "item": { "item_id": "itsgucci", "play_count": 10 } }, { "action": "delete" "item": { "item_id": "kfw", } }, { "action": "play" "item": { "item_id": "cale", } }, ]Possible operations are:
- delete - the particular item is deleted
- update - the particular item is updated with the given info
The following are convenience actions, only the 'item_id' should be included in the item block for these actions:
- play - the play count of the particular item is incremented.
- skip - the skip count of the particular item is incremented.
Here is an example response:
{ "response": { "status": { "code": 0, "message": "Success", "version": "4.2" }, "ticket": "d298131d5f189c73bd9a8ff706621443" } }The returned ticket can be used with catalog/status to check the status of the taste profile update.
retrieve the catalog-level key/values that are stored in the Taste Profile
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key. Only the API key that created a taste profile can update it format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests id yes no CANVFPJ131839D8144 The ID of the taste profile Example:
http://developer.echonest.com/api/v4/catalog/keyvalues?api_key=YOUR_API_KEY&format=json&id=CANFSZE1386B6297B9Here is an example response:
{ "response": { "keyvalues": { "cat_type": "persona", "is_active": "yes", "timestamp": "2012-07-09 06:57:00.405776", "version": "3" }, "status": { "code": 0, "message": "Success", "version": "4.2" } } }
increment the playcount for the given items by the given count.
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key. Only the API key that created a taste profile can update it format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests id yes no CANVFPJ131839D8144 The ID of the taste profile item yes yes kfw, ARK3D5J1187B9BA0B8, CAOFUDS12BB066268E:artist:kfw, 7digital-US:track:2930307 The id of the item(s) in the taste profile to be updated. This can be the simple item ID or the Rosetta ID of the item. The items must already be in the taste profile plays no no 1 - 100 Increments the play count for the specified item(s) by the given value Example:
http://developer.echonest.com/api/v4/catalog/play?api_key=YOUR_API_KEY&format=json&id=CAJTFEO131216286ED&item=ARK3D5J1187B9BA0B8Here is an example response:
{ "response": { "status": { "code": "0", "message": "Success", "version": "4" }, } }
increment the skip count for the given items by the given count
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key. Only the API key that created a taste profile can update it format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests id yes no CANVFPJ131839D8144 The ID of the taste profile item yes yes kfw, ARK3D5J1187B9BA0B8, CAOFUDS12BB066268E:artist:kfw, 7digital-US:track:2930307 The id of the item(s) in the taste profile to be updated. This can be the simple item ID or the Rosetta ID of the item. The items must already be in the taste profile skips no no 1 - 100 Increments the skip count for the specified item(s) by the given value Example:
http://developer.echonest.com/api/v4/catalog/skip?api_key=YOUR_API_KEY&format=json&id=CAJTFEO131216286ED&item=7digital-US:track:2930307Here is an example response:
{ "response": { "status": { "code": "0", "message": "Success", "version": "4" }, } }
indicates that the given items have been favorited or unfavorited.
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key. Only the API key that created a taste profile can update it format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests id yes no CANVFPJ131839D8144 The ID of the taste profile item yes yes kfw, ARK3D5J1187B9BA0B8, CAOFUDS12BB066268E:artist:kfw, 7digital-US:track:2930307 The id of the item(s) in the taste profile to be updated. This can be the simple item ID or the Rosetta ID of the item. The items must already be in the taste profile favorite no no true, false Sets the favorite flag of the specified items(s) to the given value Example:
http://developer.echonest.com/api/v4/catalog/favorite?api_key=YOUR_API_KEY&format=json&id=CAJTFEO131216286ED&item=7digital-US:track:2930307&favorite=trueHere is an example response:
{ "response": { "status": { "code": "0", "message": "Success", "version": "4" }, } }
indicates that the given items have been banned or unbanned.
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key. Only the API key that created a taste profile can update it format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests id yes no CANVFPJ131839D8144 The ID of the taste profile item yes yes kfw, ARK3D5J1187B9BA0B8, CAOFUDS12BB066268E:artist:kfw, 7digital-US:track:2930307 The id of the item(s) in the taste profile to be updated. This can be the simple item ID or the Rosetta ID of the item. The items must already be in the taste profile ban no no true, false Sets the ban flag of the specified items(s) to the given value Example:
http://developer.echonest.com/api/v4/catalog/ban?api_key=YOUR_API_KEY&format=json&id=CAJTFEO131216286ED&item=7digital-US:track:2930307&ban=trueHere is an example response:
{ "response": { "status": { "code": "0", "message": "Success", "version": "4" }, } }
apply the given rating to the given items
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key. Only the API key that created a taste profile can update it format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests id yes no CANVFPJ131839D8144 The ID of the taste profile item yes yes kfw, ARK3D5J1187B9BA0B8, CAOFUDS12BB066268E:artist:kfw, 7digital-US:track:2930307 The id of the item(s) in the taste profile to be updated. This can be the simple item ID or the Rosetta ID of the item. The items must already be in the taste profile rating no no 0 - 5 - 10 Sets the rating of the specified items(s) to the given value Example:
http://developer.echonest.com/api/v4/catalog/rate?api_key=YOUR_API_KEY&format=json&id=CAJTFEO131216286ED&item=7digital-US:track:2930307&rating=10Here is an example response:
{ "response": { "status": { "code": "0", "message": "Success", "version": "4" }, } }
Checks the status of a taste profile update.
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests ticket yes no e0ba094bbf98cd006283aa7de6780a83 The ticket to check (returned by upload or update) The response for the status call shows the status of the ticket. If the ticket could not be processed at all, then an "error" status is returned along with a "details" field that indicates why the ticket could not be processed. If any of the items were successfully processed, the ticket_status is set to "complete" and the number of items updated is returned along with a list of any items that had issues during the update. total_items is also returned for the count of items in this update, as is a percent_complete, which allows you to track completion percentage while the data associated with the ticket is being processed.
Here is an example response. This shows the results for an update where 21 items were processed and 3 failed:
{ "response": { "status": { "code": 0, "message": "Success", "version": "4.2" }, "ticket_status": "complete", "total_items": 21, "items_updated" : 21, "percent_complete": 100, "update_info" : [ { "item_id" : "1", "info":" lookup failed"}, { "item_id" : "3", "info": "bad value"} { "item_id" : "8", "info": "couldn't resolve item"} ] } }Here is an another example response that shows an error:
{ "response": { "status": { "code": 0, "message": "Success", "version": "4.2" }, "ticket_status": "error" "details": "too many items in catalog" } }
Get basic information on a taste profile
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests id one of id or name no CAJTFEO131216286ED The ID of the taste profile name one of id or name no "My Favorite Artists" The name of the taste profile Example queries:
http://developer.echonest.com/api/v4/catalog/profile?api_key=YOUR_API_KEY&format=json&id=CAJTFEO131216286ED
http://developer.echonest.com/api/v4/catalog/profile?api_key=YOUR_API_KEY&format=json&name=test_song_catalog
Here is an example response:
{ "response": { "status": { "code": "0", "message": "Success", "version": "4" }, "catalog" : { "name": "test_song_catalog", "type": "song", "id" : "CAJTFEO131216286ED", "total": 3, "resolved": 2, "pending_tickets" : [ ] } } }
Returns data stored in the taste profile. Also returns Echo Nest IDs for items that have been resolved to Echo Nest IDs along with information requested via bucket. If item_id is not set, all items (subject to the limits of the start and results parameters) are returned, otherwise, only the items explicitly specified by item_id are returned.
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests id yes no CAJTFEO131216286ED The ID of the taste profile item_id no yes MY-id-123456 The item id for the item in the taste profile bucket no yes item_keyvalues, For song items: audio_summary, artist_familiarity, artist_hotttnesss, artist_location, song_hotttnesss, song_type, tracks, id:Rosetta-space For artist items: biographies, blogs, doc_counts, familiarity, hotttnesss, images, artist_location, news, reviews, songs, terms, urls, video, years_active, id:Rosetta-space indicates what data should be returned for each item results no no 30 the desired number of results returned start no no 0 the desired index of the first result returned Example query:
http://developer.echonest.com/api/v4/catalog/read?api_key=YOUR_API_KEY&format=json&id=CAJTFEO131216286ED&bucket=audio_summary&bucket=artist_hotttnesssHere is an example response for a song taste profile:
{ "response": { "status": { "code": 0, "message": "Success", "version": "4.2" }, "catalog": { "name": "test_song_catalog", "items": [ { "song_id": "SOYRVMR12AF729F8DC", "song_name": "Harmonice Mundi II", "request": { "item_id": "0CF07A178DBF78F7", "song_name": "Harmonice Mundi II", "artist_name": "Six Organs Of Admittance" }, "artist_name": "Six Organs of Admittance", "play_count": 4, "artist_hotttnesss": 0.49929872235574302, "date_added": "2010-10-15T15:18:32", "artist_id": "ARK3D5J1187B9BA0B8", "foreign_id": "CAGPXKK12BB06F9DE9:song:SOYRVMR12AF729F8DC", "audio_summary": { "key": 4, "analysis_url": "https://echonest-analysis.s3.amazonaws.com:443/TR/TRDJDSS1264E5BB481/3/full.json?Signature=dQg3hdA7MgJ704cid6kctP7IhW8%3D&Expires=1287159130&AWSAccessKeyId=AKIAIAFEHLM3KJ2XMHRA", "energy": 0.0032362399065479839, "tempo": 113.429, "mode": 1, "time_signature": 4, "duration": 178.85995, "loudness": -23.824000000000002, "danceability": 0.16339223882299694 } }, { "favorite": true, "request": { "item_id": "DBC4B9395930FB4A", "song_name": "Spine", "artist_name": "Gem Club" }, "date_added": "2010-10-15T15:21:46" }, { "song_id": "SOJJMTV12B0B80B100", "song_name": "theologians", "request": { "item_id": "2EC046EA14A873F8", }, "artist_name": "Wilco", "track_id": "TRMAZTJ123E85978B7", "play_count": 10, "artist_hotttnesss": 0.62534933893393208, "date_added": "2010-10-15T15:24:17", "foreign_id": "CAGPXKK12BB06F9DE9:song:2EC046EA14A873F8", "artist_id": "AR6SPRZ1187FB4958B", "audio_summary": { "key": 2, "analysis_url": "https://echonest-analysis.s3.amazonaws.com:443/TR/TRMAZTJ123E85978B7/3/full.json?Signature=TjzpSgav0iNDx9CNvG1OzYd0QjE%3D&Expires=1287159130&AWSAccessKeyId=AKIAIAFEHLM3KJ2XMHRA", "energy": null, "tempo": 111.544, "mode": 0, "time_signature": 4, "duration": 218.85342, "loudness": -10.044, "danceability": null } } ], "start": 0, "total": 3, "type": "song", "id": "CAGPXKK12BB06F9DE9" } } }Here is an example response for a general taste profile:
{ "response": { "status": { "code": 0, "message": "Success", "version": "4.2" }, "catalog": { "name": "test_general_catalog", "items": [ { "artist_id": "AR39A3F1187FB4BDEC", "artist_name": "JR", "date_added": "2011-08-29T16:25:50", "foreign_id": "CAABOUD13216257FC7:artist:0", "request": { "item_id": "0", "artist_name": " JR" } }, { "song_id": "SOYRVMR12AF729F8DC", "song_name": "Harmonice Mundi II", "request": { "item_id": "0CF07A178DBF78F7", "song_name": "Harmonice Mundi II", "artist_name": "Six Organs Of Admittance" }, "artist_name": "Six Organs of Admittance", "play_count": 4, "artist_hotttnesss": 0.49929872235574302, "date_added": "2010-10-15T15:18:32", "artist_id": "ARK3D5J1187B9BA0B8", "foreign_id": "CAGPXKK12BB06F9DE9:song:SOYRVMR12AF729F8DC", "audio_summary": { "key": 4, "analysis_url": "https://echonest-analysis.s3.amazonaws.com:443/TR/TRDJDSS1264E5BB481/3/full.json", "energy": 0.0032362399065479839, "tempo": 113.429, "mode": 1, "time_signature": 4, "duration": 178.85995, "loudness": -23.824000000000002, "danceability": 0.16339223882299694 } }, { "favorite": true, "request": { "item_id": "DBC4B9395930FB4A", "song_name": "Spine", "artist_name": "Gem Club" }, "date_added": "2010-10-15T15:21:46" }, { "song_id": "SOJJMTV12B0B80B100", "song_name": "theologians", "request": { "item_id": "2EC046EA14A873F8", }, "artist_name": "Wilco", "track_id": "TRMAZTJ123E85978B7", "play_count": 10, "artist_hotttnesss": 0.62534933893393208, "date_added": "2010-10-15T15:24:17", "foreign_id": "CAGPXKK12BB06F9DE9:song:2EC046EA14A873F8", "artist_id": "AR6SPRZ1187FB4958B", "audio_summary": { "key": 2, "analysis_url": "https://echonest-analysis.s3.amazonaws.com:443/TR/TRMAZTJ123E85978B7/3/full.json", "energy": null, "tempo": 111.544, "mode": 0, "time_signature": 4, "duration": 218.85342, "loudness": -10.044, "danceability": null } } ], "start": 0, "total": 3, "type": "song", "id": "CAGPXKK12BB06F9DE9" } } }Only items that have been properly resolved will have bucket info returned for them. Fields such as "rating" that have not been set will not be returned.
Returns feeds based on the artists in a taste profile. Unlike catalog/read method, the catalog/feed method interleaves items and sorts them by date.
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests id yes no CAGPXKK12BB06F9DE9 The ID of the taste profile bucket no yes can be any combination of news, blogs, reviews, audio and video blogs. If omitted defaults to news. indicates what type of feed items should be returned for each artist in the taste profile results no no 25 the desired number of results returned start no no 0 the desired index of the first result returned since no no if supplied must be in date format YYYY-mm-dd limit the items to those that have occurred since the given date high_relevance no no true, false if true only items that are highly relevant for this artist will be returned. Currently only news items are filtered for high relevance Example query:
http://developer.echonest.com/api/v4/catalog/feed?api_key=YOUR_API_KEY&format=json&id=CANVFPJ131839D8144&since=2011-2-8&results=2&bucket=blogsHere is an example response for a taste profile feed:
{ "response": { "status": { "code": 0, "message": "Success", "version": "4.2" }, feed: [ { name: "Rock-A-Rolla 30 + t-shirt Om" url: http://amplificasom.blogspot.com/2011/02/rock-rolla-30-t-shirt-om.html date_posted: "2011-02-08T10:52:00" summary: " para capa da Rock-A-Rolla, pelo que podemos esperar novas escolhas impares e muitas surpresas fascinantes... A Rock-a-rolla tem distribuição exclusiva em Portugal via Amplificasom. Rock-A-Rolla 30: EARTH, <span>SIX</span> <span>ORGANS</span> OF <span>ADMITTANCE</span>, THE SKULL DEFEKTS, OVO, TIM HECKER, MUGSTAR, IGORRR, MACHINEFABRIEK, THE KILIMANJARO DARKJAZZ ENSEMBLE, IROHA, RIOT SEASON, 2011 PREVIEW Ao vivo: ATARI TEENAGE RIOT, LAIBACH, BLACK BREATH, SHRINEBUILDER + NEUROSIS, MARNIE STERN, GODSPEED YOU! BLACK EMPEROR ; PLUS OVER ... " date_found: "2011-02-08T18:29:58" references: [ { artist_id: "ARK3D5J1187B9BA0B8" artist_name: "Six Organs of Admittance" } ] type: "blogs" id: "5ad9bfcb2e9ae53109ddb677dd54540a" } { name: "Live: The Autumn Defense @ Troubadour, 2.05.11" url: http://www.rawkblog.net/2011/02/live-the-autumn-defense-troubadour-2-05-11/ date_posted: "2011-02-08T10:00:31" summary: "All photos by David Greenwald I imagine the Autumn Defense's John Stirratt and Pat Sansone had to steal a few days away from <span>Wilco</span>'s new album sessions to play their California shows. But given the band's '70s-indebted folk-rock sound, one born mostly in Laurel Canyon and West L.A. venues such as the Troubadour itself, it would've been a shame to let an album cycle pass by without coming to what could've been their home turf in some earlier era. The time machine was in full effect ... " date_found: "2011-02-08T11:02:45" references: [ { artist_id: "AR6SPRZ1187FB4958B" artist_name: "Wilco" } ] type: "blogs" id: "b489c3a190604dde358ae245833c99ec" } ] } }Only feeds for the items that have been properly resolved will be returned.
Deletes the entire taste profile. Only the API key used to create a taste profile can be used to delete that taste profile.
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests id yes no CANVFPJ131839D8144 The ID of the taste profile Warning
This method requires an HTTP Post request.
Example post:
curl -F "api_key=YOUR_API_KEY" -F "format=json" -F "id=CANVFPJ131839D8144" "http://developer.echonest.com/api/v4/catalog/delete"Here is an example response:
{ "response": { "status": { "code": 0, "message": "Success", "version": "4.2" }, "name": "test_artist_catalog", "id": "CAOFUDS12BB066268E" } }
Returns a list of all taste profiles created on this key
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests results no no 30 the number of results desired start no no 0 the desired index of the first result returned Example query:
http://developer.echonest.com/api/v4/catalog/list?api_key=YOUR_API_KEY&format=jsonHere is an example response:
{ "response": { "status": { "code": "0", "message": "Success", "version": "4" }, "start": 0, "total": 2, "catalogs" : [ { "id" : "CAOFUDS12BB066268E" "name": "test_artist_catalog" "type": "artist", "total": 4 }, { "id" : "CAGPXKK12BB06F9DE9" "name": "test_song_catalog" "type": "song", "total": 3 } ] } }
Returns a list of all taste profiles that are similar to the given set of taste profiles. This method returns similar taste profiles of the given use type. Similarity search is restricted to taste profiles that were created with the caller's API key.
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests id yes yes (up to 10) CANVFPJ131839D8144 The ID of the taste profile results no no 30 the number of results desired start no no 0, 15, 30 the desired index of the first result returned keyvalue no yes key or key:value type:station gender:female zipcode:03103 restrict results to taste profiles that have the given key/value pair. If no value is given, restrict results to all taste profiles that have the given key. Example query:
http://developer.echonest.com/api/v4/catalog/similar?api_key=YOUR_API_KEY&format=json&id=CAKSMUX1321A708AA4&results=2Here is an example response:
{ "response": { "status": { "code": "0", "message": "Success", "version": "4" }, "similars" : [ { "id" : "CAOFUDS12BB066268E" "name": "test_artist_catalog" "type": "artist", "total": 4, "score" : 0.821 }, { "id" : "CAGPXKK12BB06F9DE9" "name": "test_song_catalog" "type": "song", "total": 3, "score" : 0.721 } ] } }Example query limiting results to 'user' taste profiles:
http://developer.echonest.com/api/v4/catalog/similar?api_key=YOUR_API_KEY&format=json&keyvalue=type:user&results=1&id=CAKSMUX1321A708AA4Here is an example response:
{ "response": { "status": { "code": "0", "message": "Success", "version": "4" }, "similars" : [ { "id" : "CAGPXKK12BB06F9DE9" "name": "test_song_catalog" "type": "song", "total": 3, "score" : 0.721 } ] } }
Access the taste profile attributes.
Taste Profile Attributes are scores and summaries that can help developers more easily leverage the capabilities of Echo Nest Taste Profiles. These attributes are calculated for each individual Taste Profile, and are based on the musical characteristics we've seen that help describe a listener musically. In this alpha release, we are making the following attributes available:
- Diversity - measures the overall diversity of a listener’s taste by mapping the "distance" between musical styles present in the Taste Profile.
- Mainstreamness - measures the overall familiarity of a user’s listening activity to determine preference for either mainstream or more obscure music.
- Freshness - measures listening habits to determine how much a user cares about new album releases vs. sticking with older music.
- Adventurouness - measures how open the listener is to music outside of his or her musical comfort zone.
Parameters:
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests id yes no CANVFPJ131839D8144 The ID of the taste profile category yes yes adventurousness, diversity, freshness, mainstreamness, top_years, top_styles, audio_features The attributes to be returned for the taste profile Note - audio features are only available for song-based Taste Profiles
Important notes on the alpha release: We are making Taste Profile Attributes available in the API on a restricted and limited basis, and are looking forward to your feedback. However, it is important to fully understand these limitations before you start: We cannot provide support for these attributes. If you're working on something and the attribute API breaks, please let us know, but unfortunately we may not be able to provide a timeline for a fix. We cannot provide any guarantees on performance (uptime, response time, or variability). API endpoints and method names may change, and previous names will be swiftly deprecated. We encourage you to hack away on these, and give us feedback on what's useful, what's broken, or what you'd like to see next. However, we strongly discourage developers from building mission-critical functionality until these attributes have been released in beta.
Example query:
http://developer.echonest.com/api/v4/catalog/predict?api_key=YOUR_API_KEY&format=json&id=CANVFPJ131839D8144&category=mainstreamness&category=freshnessHere is an example response:
{ "response": { "catalog": { "id": "CANVFPJ131839D8144", "name": "just_one", "predictions": [ { "category": "mainstreamness", "results": 0.7081548461538462 }, { "category": "freshness", "results": 0.6414835164835164 } ], "type": "artist" }, "status": { "code": 0, "message": "Success", "version": "4.2" } } }