API calls for managing taste profiles
The catalog 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. 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 catalog items to Echo Nest IDs and then retrieve info such as song tempo for a large catalog of items.
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 foreign catalog 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.
Catalogs are typed; a catalog can be an 'artist' catalog or a 'song' catalog. An 'artist' catalog can contain only artists. A 'song' catalog can contain only songs.
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 catalog update.
The resolution process involves taking whatever information is provided for an item (artist name, release name, song name, ENMFP fingerprint code, etc) and attempting to resolve it to an Echo Nest ID.
Creates a catalog.
Parameter Required? Multiple? Values Description api_key yes no N6E4NIOVYMTHNDM8J 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 catalog type yes no artist, song The type of the catalog Warning
This method requires an HTTP Post request with Content-Type "multipart/form-data"
Example post:
curl -F "api_key=N6E4NIOVYMTHNDM8J" -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 catalog. The body of the post should include an item block that describes modifications to the catalog.
When a catalog is updated, the contents of the catalog 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 N6E4NIOVYMTHNDM8J your API key. Only the API key that created a catalog 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 catalog 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=N6E4NIOVYMTHNDM8J" -F "data_type=json" -F "format=json" -F "id=CAJTFEO131216286ED" -F "data=@data_file.json"The format for the json item block for song catalogs 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] "fp_code": {"version":3.15, "code":ENMFP code} [OPTIONAL] or "fp_code": ENMFP code [OPTIONAL] (see the note about fp_code version key below) "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] } } ]Note that the item_id will be hashed with the catalog ID and the catalog 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, '.', '_', '-'.
Another note is about fp_code format: fp_code can be passed in either as a string or a dictionary. Dictionary format allows to specify the version of ENMFP to be used. Currently supported versions are 3.15 and 4.0. If the version is not specified in the dictionary or fp_code passed in as a string, version 3.15 is used.
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 catalog:
[ { "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", "fp_code": "eJxllEu2LSkIBaekgqjDST_Mfwgv9rnVq04sIFOBLVraKKW0-YF1wCfsB45whQeM34Cs1oB867LCwQgwhSV8E2zhCFd45LAEXsjhVVaTZS7Icrb3LktV-RQWOfwTtv47wiWHPyFBL_zYq9AEE7wJ5OhdCDbtQ5jCIlH_BLzSr_C0IkFQYYkqNMHIES50do4Q1G9ItViCVIst68iSaiHVInFHZfsh1YZUG8aHEXIl2FCD45MlwYYEG2pwSLChDWbBmpVlswkUBWSFrMEGc_6gnz_FpNU8fJ7aakqrmey8tNWS9qsJJjjLVme_JZmWDmstS1QrhsyeB79cUPvFN6999jHwLz8RxB8K2rr4t9S13-j4p0XkutZ2lrV2TT9fntZYrWA5d_WbzmSZRR_KcwjWZ8rDIPmYSXDbWwSZl3by48vdhWD5zjGKrv4a3m3hHP930Iri_BEak6C9d0wdlpp708pwCfzqeJfDr43OchPM83kf79c_wf_1X-ev_5LDQ8HV7d46ab11z9FiIxrB09Z3f_1n-WLXklk2fae50b_tt88tWb_38ksrZ8XeXLuDKgymnWXmYK1s_p8e49BS_9MDsWt_ZvWrjHmnzxPTq81xbBCM-mqWS15OZo5CdXajVsZpdfIywUmw3et1UZC3PTrznsaE3Nss93neyD_zUZ90CFMtfzqsWAqiQ_TPz58OK8zjTwfkqvOnA4fF3Rmk-xb633rVP_fOfFDpu1z1iyb036VzShTjClHhQde7mTPekc49vPRL8VxD5ihQl_O3X3B1himd9eQn2A_nRKf73t9QxW45OtPIu3P2rXF_QUO7HbxgzEQnyO1uLHbMuiYj1nrfHlG5s6vr-_HkqC2yboJm7e4T1Gnn7EiuOe1b48Wrh_YZdF4o7n4tc407_wGju1iQ", "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 catalogs 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 catalog:
[ { "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 catalog update.
Checks the status of a catalog update.
Parameter Required? Multiple? Values Description api_key yes no N6E4NIOVYMTHNDM8J 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 catalog
Parameter Required? Multiple? Values Description api_key yes no N6E4NIOVYMTHNDM8J 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 catalog name one of id or name no "My Favorite Artists" The name of the catalog Example queries:
http://developer.echonest.com/api/v4/catalog/profile?api_key=N6E4NIOVYMTHNDM8J&format=json&id=CAJTFEO131216286ED
http://developer.echonest.com/api/v4/catalog/profile?api_key=N6E4NIOVYMTHNDM8J&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 catalog. 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 N6E4NIOVYMTHNDM8J 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 catalog item_id no yes MY-id-123456 The item id for the item in the catalog bucket no yes kvstore, For song items: audio_summary, artist_familiarity, artist_hotttnesss, artist_location, song_hotttnesss, tracks, id:Rosetta-space For artist items: biographies, blogs, doc_counts, familiarity, hotttnesss, images, 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=N6E4NIOVYMTHNDM8J&format=json&id=CAJTFEO131216286ED&bucket=audio_summary&bucket=artist_hotttnesssHere is an example response for a song catalog:
{ "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", "fp_code": "eJxllEu2LSkIBaekgqjDST_Mfwgv9rnVq04sIFOBLVraKKW0-YF1wCfsB45whQeM34Cs1oB867LCwQgwhSV8E2zhCFd45LAEXsjhVVaTZS7Icrb3LktV-RQWOfwTtv47wiWHPyFBL_zYq9AEE7wJ5OhdCDbtQ5jCIlH_BLzSr_C0IkFQYYkqNMHIES50do4Q1G9ItViCVIst68iSaiHVInFHZfsh1YZUG8aHEXIl2FCD45MlwYYEG2pwSLChDWbBmpVlswkUBWSFrMEGc_6gnz_FpNU8fJ7aakqrmey8tNWS9qsJJjjLVme_JZmWDmstS1QrhsyeB79cUPvFN6999jHwLz8RxB8K2rr4t9S13-j4p0XkutZ2lrV2TT9fntZYrWA5d_WbzmSZRR_KcwjWZ8rDIPmYSXDbWwSZl3by48vdhWD5zjGKrv4a3m3hHP930Iri_BEak6C9d0wdlpp708pwCfzqeJfDr43OchPM83kf79c_wf_1X-ev_5LDQ8HV7d46ab11z9FiIxrB09Z3f_1n-WLXklk2fae50b_tt88tWb_38ksrZ8XeXLuDKgymnWXmYK1s_p8e49BS_9MDsWt_ZvWrjHmnzxPTq81xbBCM-mqWS15OZo5CdXajVsZpdfIywUmw3et1UZC3PTrznsaE3Nss93neyD_zUZ90CFMtfzqsWAqiQ_TPz58OK8zjTwfkqvOnA4fF3Rmk-xb633rVP_fOfFDpu1z1iyb036VzShTjClHhQde7mTPekc49vPRL8VxD5ihQl_O3X3B1himd9eQn2A_nRKf73t9QxW45OtPIu3P2rXF_QUO7HbxgzEQnyO1uLHbMuiYj1nrfHlG5s6vr-_HkqC2yboJm7e4T1Gnn7EiuOe1b48Wrh_YZdF4o7n4tc407_wGju1iQ" }, "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" } } }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 N6E4NIOVYMTHNDM8J 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 catalog 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 catalog 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=N6E4NIOVYMTHNDM8J&format=json&id=CANVFPJ131839D8144&since=2011-2-8&results=2&bucket=blogsHere is an example response for a catalog 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 catalog. Only the API key used to create a catalog can be used to delete that catalog.
Parameter Required? Multiple? Values Description api_key yes no N6E4NIOVYMTHNDM8J 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 catalog Warning
This method requires an HTTP Post request with Content-Type "multipart/form-data"
Example post:
curl -F "api_key=N6E4NIOVYMTHNDM8J" -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 catalogs created on this key
Parameter Required? Multiple? Values Description api_key yes no N6E4NIOVYMTHNDM8J 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=N6E4NIOVYMTHNDM8J&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 } ] } }