Creating and populating a taste profile

This tutorial walks through the process of creating a taste profile

Creating a taste profile

To create a taste profile, use the catalog/create method. This method takes the name of the taste profile, along with the type (currently artist or song) and will create a catalog representing that profile. A catalog is associated with your API_KEY. Any operations that write to the profile (such as update or delete) can only be performed on a taste profile that was created with a matching API_KEY. Read-only calls such as profile or read don't require a matchig API_KEY.

Taste profile creation requies an HTTP post request.

Example Creation

curl -F "api_key=FILDTEOIK2HBORODV" -F "format=json" -F "type=artist" -F "name=test_artist_catalog" "http://developer.echonest.com/api/v4/catalog/create"

Response

    {
      "response": {
        "status": {
          "code": 0,
          "message": "Success",
          "version": "4.2"
        },
        "name": "test_artist_catalog",
        "id": "CAOFUDS12BB066268E"
        "type": "artist"
      }
    }

Updating a taste profile

To add items to a taste profile, you create a JSON item block containing all of the items to be added and post it via the catalog/update call. The format of the JSON item block is:
[
 {
 "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]   (note that fp_code can be a string or a dictionary))

         "song_id": rosetta ID OR ENID [OPTIONAL]
         "song_name": song name [OPTIONAL] (song_name and song_id are mutually exclusive)

         // artist info should not be specified if a song_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]
     }
  }
 ]
The JSON blog is a list of dictionaries, one per item. The dictionary contains an 'item' key and an optional 'action' key (the default action is to 'update' the item). An item should always contain an item_id and some form of identification. For example, an artist item should either have an artist_name or an artist_id field, while a song item should have at either a song_id or an artist_name and song_name). When a new item is added to a taste profile, the item is resolved to an Echo Nest ID. This allows your item to be associated with all of the data that Echo Nest associates with the item. Once an item has been resolved successfully, you can retrieve all of the Echo Nest data for the item. The item resolution can take some time, therefore, it happens asynchronously. The update method returns a 'ticket' that can be used with the catalog/status call to determine when an update has completed.

Update Example

curl -X POST "http://developer.echonest.com/api/v4/catalog/update" -F "api_key=FILDTEOIK2HBORODV" -F "data_type=json" -F "format=json" -F "id=CAOFUDS12BB066268E" -F "data=@data_file.json"

Response

    {
      "response": {
        "status": {
          "code": 0,
          "message": "Success",
          "version": "4.2"
        },
        "ticket": "d298131d5f189c73bd9a8ff706621443"
      }
    }

Checking the status of an update

The catalog/update call returns a 'ticket' that can be used to determine the status of the catalog update. When you call catalog/status with a ticket you get a response that indicates the status of the ticket.

Example of checking the statuts

Response

    {
      "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"}
        ]
      }
    }