Taste Profile API Methods

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.

Predefined key/value attributes The following keys/values are pre-defined attributes can be used to store information a user associated with the taste profile. This information can be used to help increase the understanding of the audience via the predict api.

The following predefined attributes are validated to ensure that values are formatted properly:

  • _yob - 4-digit year of birth such as "1989"
  • _gender - One of "male", "female", "m", "f", case-insensitive
  • _locale - POSIX-style locale, such as "en_US" or "en_US.UTF-8" or "en" (note that .codeset and @modifier are ignored).
  • _country_code - two- or three- letter country code for user country, such as "us".
  • _latlng - latitude and longitude as comma separated numbers encoded as a string such as "42.396,-71.120"
  • _postal_code - string <= 15 characters Appropriate zip code or postal code, as known as a 15 or less character string
  • _platforms - list of strings - List of platforms a user has used. Valid list elements are 'web', 'connected_device', 'auto', and 'mobile'.
  • _paid_user - 'true', 'false', an indication if the user associated with this taste profile is a paid user
  • _trial_user - 'true', 'false', an indication if this taste profile user is in a trial period or not.
  • _ad_supported_user - 'true', 'false', an indication of whether this taste profile user is exposed to ads or not
  • _first_session - Timestamp of first playlist session in ISO 8601 format
  • _last_session - Timestamp of most recent playlist session in ISO 8601 format
  • _number_of_sessions - Count of number of playlist sessions as a string
  • _user_followers - Count of other users on a service that follow this user as a string
  • _user_following - Count of other users on the service that this user follows as a string
  • _playlist_followers - Count of other users following this user's playlists as a string
  • _playlist_following - Count of playlists on the service this user follows as a string

The following predefined attributes are supported but are not constrained to any format, nor are they validated:

  • _country - Common-name for user country
  • _education - Common-name for user country
  • _languages - Common-name for user country
  • _location_name - Common-name for user country

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.

The rules for resolution for song taste profile are:
  • the song fields ('song_id', 'song_name' or 'track_id') and artist fields ('artist_id' or 'artist_name') are used to search for the closest matching song.
  • If a song item is updated with different identity information (song or artist), the item is treated as a new item and resolved from scratch.
  • When an item is properly resolved, the Echo Nest song ID is attached to the item.
The rules for resolution for artist taste profiles are:
  • The artist fields ('artist_name' or 'artist_id') are used to search for the closest matching artist.
The rules for resolution for general taste profile are:
  • if an item update has any 'song' level information (song_id, song_name, track_id only), the item is considered to be a 'song' and resolved accordingly.
  • If the request does not have any song-level information, then the item is resolved as an artist.

create

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",
  }
}

update

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.

keyvalues

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=CANFSZE1386B6297B9

Here 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"
        }
    }
}

play

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=ARK3D5J1187B9BA0B8

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4"
    },
  }
}

favorite

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=true

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4"
    },
  }
}

ban

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=true

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4"
    },
  }
}

rate

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=10

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4"
    },
  }
}

status

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"
  }
}
Ticket Status
Possible ticket status values are:
  • unknown - the ticket is not a known ticket
  • pending - the update associated with the ticket is in process
  • complete - the update associated with the ticket is complete
  • error - the update could not be processed. The details field may contain a description of the error.

profile

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" : [ ]
    }
  }
}

read

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_discovery, artist_discovery_rank, artist_familiarity, artist_familiarity_rank, artist_hotttnesss, artist_hotttnesss_rank, artist_location, song_currency, song_currency_rank, song_hotttnesss, song_hotttnesss_rank, song_type, tracks, id:Rosetta-space For artist items: 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 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_hotttnesss

Here 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.

feed

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=blogs

Here 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.

delete

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

list

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=json

Here 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
        }
        ]
    }
}

similar (beta)

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=2

Here 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=CAKSMUX1321A708AA4

Here 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
        }
     ]
   }
}

predict (alpha)

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.
In addition, the method allows you to access helpful histogram buckets across a listener's Taste Profile:
  • Top styles - a list of the styles that appear in a taste profile, and counts of the occurrence of each.
  • Top years - a list of start years for the artists in a taste profile, and counts for each year.
  • Audio features - bucketed breakdowns of the energy, danceability, loudness, and tempo bands of the songs that appear in a taste profile, and counts for each bucket. (This category requires a song-based profile.)

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=freshness

Here 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"
        }
    }
}