Song API Methods

Api calls for getting data about songs.

Buckets: Some song methods such as search, profile, and identify accept a bucket parameter. This parameter allows you to specify what additional data should be returned with each song. Multiple buckets can be specified simultaneously allowing you to request multiple sets of data in a single call. Possible song buckets are:

Bucket	Description
audio_summary	returns summary audio parameters for the song
artist_familiarity	returns the familiarity for the song's artist
artist_hotttnesss	returns the hotttnesss for the song's artist
artist_location	returns information about the location of origin for the song's artist
song_hotttnesss	returns the hotttnesss of the song
song_type	returns a list of song types for the song. Possible song types returned are: 'christmas', 'live' and 'studio'
tracks	returns detailed track information for the song. You must also specify a Rosetta id space such as 7digital-US.
id:rosetta-catalog	returns catalog specific information about the song for the given catalog. See Project Rosetta Stone for details.
id:Personal-Catalog-ID	returns personal catalog specific information about the song for the given catalog. See Project Rosetta Stone for details.

search

Search for songs given different query types

Parameter	Required?	Multiple?	Values	Description
api_key	yes	no	YOUR API KEY	Your API key
format	no	no	json, xml	the format of the results
title	no	no	my iron lung	the title of the song
artist	no	no	radiohead	the name of the primary artist
combined	no	no	radiohead karma police	query both artist and title fields
description	no	yes	Some examples are: alt-rock,-emo, harp^2.	a description of the artist.
style	no	yes	jazz, metal^2	a musical style or genre like rock, jazz, or funky. See the method list_terms for details on what styles are currently available
mood	no	yes	happy, sad^.5	a mood like happy or sad. See the method list_terms for details on what moods are currently available
rank_type	no	no	relevance, familiarity	For search by description, style or mood indicates whether results should be ranked by query relevance or by artist familiarity
artist_id	no	no	ARH6W4X1187B99274F	the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
results	no	no	0 - 100 (default = 15)	the desired number of results to return
start	no	no	0, 15, 30	the desired index of the first result returned
song_type	no	yes	christmas, live, studio	controls the type of songs returned. Supported song_types are: 'christmas', 'live' and 'studio'. A song type can optionally be followed by ':' and a state, where the state can be one of 'true', 'false' or 'any'. If no state is given, the desired state is assumed to be 'true'.
max_tempo	no	no	0.0 < tempo < 500.0 (BPM)	the maximum tempo for the song
min_tempo	no	no	0.0 < tempo < 500.0 (BPM)	the minimum tempo for the song
max_duration	no	no	0.0 < duration < 3600.0 (seconds)	the maximum duration of any song
min_duration	no	no	0.0 < duration < 3600.0 (seconds)	the minimum duration of any song
max_loudness	no	no	-100.0 < loudness < 100.0 (dB)	the maximum loudness of any song
min_loudness	no	no	-100.0 < loudness < 100.0 (dB)	the minimum loudness of any song
artist_max_familiarity	no	no	0.0 < familiarity < 1.0	the maximum familiarity of any song
artist_min_familiarity	no	no	0.0 < familiarity < 1.0	the minimum familiarity of any song
artist_start_year_before	no	no	1970, 2011, present	Matches artists that have an earliest start year before the given value
artist_start_year_after	no	no	1970, 2011, present	Matches artists that have an earliest start year after the given value
artist_end_year_before	no	no	1970, 2011, present	Matches artists that have a latest end year before the given value
artist_end_year_after	no	no	1970, 2011, present	Matches artists that have a latest end year after the given value
song_max_hotttnesss	no	no	0.0 < hotttnesss < 1.0	the maxiumum hotttnesss of any song
song_min_hotttnesss	no	no	0.0 < hotttnesss < 1.0	the minimum hotttnesss of any song
artist_max_hotttnesss	no	no	0.0 < hotttnesss < 1.0	the maxiumum hotttnesss of any song's artist
artist_min_hotttnesss	no	no	0.0 < hotttnesss < 1.0	the minimum hotttnesss of any song's artist
min_longitude	no	no	-180.0 < longitude < 180.0	the minimum longitude of the primary artist location
max_longitude	no	no	-180.0 < longitude < 180.0	the maximum longitude of the primary artist location
min_latitude	no	no	-90.0 < latitude < 90.0	the minimum latitude of the primary artist location
max_latitude	no	no	-90.0 < latitude < 90.0	the maximum latitude of the primary artist location
max_danceability	no	no	0.0 < danceability < 1.0	the maximum danceability of any song
min_danceability	no	no	0.0 < danceability < 1.0	the minimum danceability of any song
max_energy	no	no	0.0 < energy < 1.0	the maximum energy of any song
min_energy	no	no	0.0 < energy < 1.0	the minimum energy of any song
min_liveness	no	no	0.0 < liveness < 1.0	the minimum liveness of any song
max_liveness	no	no	0.0 < liveness < 1.0	the maximum liveness of any song
min_speechiness	no	no	0.0 < speechiness < 1.0	the minimum speechiness of any song
max_speechiness	no	no	0.0 < speechiness < 1.0	the maximum speechiness of any song
mode	no	no	(minor, major) 0, 1	the mode of songs
key	no	no	(c, c-sharp, d, e-flat, e, f, f-sharp, g, a-flat, a, b-flat, b) 0 - 11	the key of songs in the playlist
bucket	no	yes	audio_summary, artist_familiarity, artist_hotttnesss, artist_location, song_hotttnesss, song_type, tracks, id:Rosetta-space	indicates what data should be returned for each song. If specifying the "tracks" bucket, a bucket with an id space must also be specified. See Project Rosetta Stone for details on retrieving information associated with a particular catalog.
sort	no	no	tempo-asc, duration-asc, loudness-asc, speechiness-asc, liveness-asc, artist_familiarity-asc, artist_hotttnesss-asc, artist_start_year-asc, artist_start_year-desc, artist_end_year-asc, artist_end_year-desc, song_hotttness-asc, latitude-asc, longitude-asc, mode-asc, key-asc, tempo-desc, duration-desc, loudness-desc, liveness-desc, speechiness-desc, artist_familiarity-desc, artist_hotttnesss-desc, song_hotttnesss-desc, latitude-desc, longitude-desc, mode-desc, key-desc, energy-asc, energy-desc, danceability-asc, danceability-desc	indicates how the songs results should be ordered
limit	no	no	true, false	if 'true', limit the results to any of the given idspaces or catalogs

Warning

Description cannot be used in conjunction with title, artist, combined, or artist_id.

Description, style mood: Each description style or mood term must be in its own parameter. Terms can be boosted. To boost a term use the caret, "^", symbol with a boost factor (a number) at the end of the term you are searching. The higher the boost factor, the more relevant the term will be. To prohibit a term from appearing in the result artists, prepend, a "-". To require a term, prepend a '+' (which must be encoded as %2b) or alternatively, to avoid having to encode the plus you can prepend a '^'.

Example descriptions:

description=quirky&style=indie&mood=chill^1.2

To ban country use

style=-country

Example query:

http://developer.echonest.com/api/v4/song/search?api_key=YOUR_API_KEY&format=json&results=1&artist=radiohead&title=karma%20police

Here is an example response:

{
  "response": {
    "status": {
      "code": 0,
      "message": "Success",
      "version": "4.2"
    },
    "songs": [
      {
        "artist_id": "ARH6W4X1187B99274F",
        "id": "SOCZZBT12A6310F251",
        "artist_name": "Radiohead",
        "title": "Karma Police"
      }
    ]
  }
}

If Rosetta Stone ID spaces are requested, the foreign IDs of the tracks are returned in a foreign ID block like so:

http://developer.echonest.com/api/v4/song/search?api_key=YOUR_API_KEY&format=json&results=1&artist=radiohead&title=karma%20police&bucket=id:7digital-US&bucket=audio_summary&bucket=tracks

Here is an example response:

{
 "response": {
     "status": {
         "version": "4.2",
         "code": 0,
         "message": "Success"
     },
     "songs": [{
         "title": "Karma Police",
         "artist_name": "Radiohead",
         "tracks": [{
             "catalog": "7digital-US",
             "foreign_id": "7digital-US:track:2748611",
             "release_image": "http://cdn.7static.com/static/img/sleeveart/00/002/577/0000257700_200.jpg",
             "id": "TRKGPQB128F4252E52",
             "preview_url": "http://previews.7digital.com/clips/34/2748611.clip.mp3"
         }
     }]
 }
}

Please note that you need to add 'tracks' bucket to get detailed track info for the given ID spaces.

Song Type

Songs can have one or more song types associated with them. Currently supported song types are:

• christmas - songs that are appropriate to play during the Christmas holiday season
• live - songs that were performed in front of an audience
• studio - songs that were recorded in a studio

When searching for songs, a song_type parameter can be used to restrict results to songs that have a matching song_type state. The state can be one of the following values:

• true - only return songs tagged as given type. If no state is given, 'true' is assumed.
• false - only return songs not tagged as given type
• any - any songs can be returned, whether they match the type or not.

The syntax for setting a song type is as follows:

• song_type=christmas - sets christmas song type to true
• song_type=christmas:true - sets christmas song type to true
• song_type=christmas:false - sets christmas song type to false
• song_type=christmas:any - sets christmas song type to any

Examples of search using song_type

Find Christmas songs by 'Weezer':

http://developer.echonest.com/api/v4/song/search?api_key=YOUR_API_KEY&format=json&artist=weezer&song_type=christmas&bucket=song_type

Find non-Christmas songs by 'Bing Crosby':

http://developer.echonest.com/api/v4/song/search?api_key=YOUR_API_KEY&format=json&artist=Bing+Crosby&song_type=christmas:false&bucket=song_type

Find live performances by 'Radiohead':

http://developer.echonest.com/api/v4/song/search?api_key=YOUR_API_KEY&format=json&artist=Radiohead&song_type=live&bucket=song_type

Find studio performances by 'Deerhoof':

http://developer.echonest.com/api/v4/song/search?api_key=YOUR_API_KEY&format=json&artist=Deerhoof&song_type=studio&bucket=song_type

profile

Get info about songs given a list of ids

Parameter	Required?	Multiple?	Values	Description
api_key	yes	no	YOUR API KEY	your API key
id	yes	no	SOCZMFK12AC468668F	the song ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
track_id	yes	no	TRTLKZV12E5AC92E11	The Echo Nest or Rosetta ID of a track. The track ID is mapped to the corresponding song ID. (See Project Rosetta Stone)
format	no	no	json, xml	the format of the output
bucket	no	yes	audio_summary, artist_familiarity, artist_hotttnesss, artist_location, song_hotttnesss, song_type, tracks, id:Rosetta-space	indicates what data should be returned for each song. If specifying the "tracks" bucket, a bucket with an id space must also be specified.
limit	no	no	true, false	if 'true', limit the results to any of the given idspaces or catalogs

Example query:

http://developer.echonest.com/api/v4/song/profile?api_key=YOUR_API_KEY&format=json&id=SOCZMFK12AC468668F

Here is an example response:

{
  "response": {
    "status": {
      "code": 0,
      "message": "Success",
      "version": "4.2"
    },
    "songs": [
      {
        "artist_id": "ARCQMJH1187B9B53CC",
        "id": "SOCZMFK12AC468668F",
        "artist_name": "DJ Screw",
        "title": "Stay Fly"
      }
    ]
  }
}

identify

Identifies a song given an Echoprint or Echo Nest Musical Fingerprint hash codes.

Parameter	Required?	Multiple?	Values	Description
api_key	yes	no	YOUR_API_KEY	your API key
query	no	no	json string (use only with POST, see below)	the JSON query, see below
code	no	no	code string (use only with GET, see below)	the FP hashcodes for the track
artist	no	no	Michael+Jackson,	the name of the artist from the ID3 tag- (use only with GET, see below)
title	no	no	Billie+Jean	the title of the track from the ID3 tag - text (use only with using GET, see below)
release	no	no	Thriller	the title of the album/release from the ID3 tag - text (use only with GET, see below)
duration	no	no	296.15	the length of time of the track, in seconds - text (use only with GET, see below)
genre	no	no	pop	the genre from the ID3 tag (use only with GET, see below)
version	no	no	3.15	version of codegen used to generate the code. Currently supported versions are 3.15 for ENMFP and 4.12 for Echoprint. If not specified, version 3.15 is used. See the section below on Echo Nest Fingerprinting systems to determine which fingerprinting system is best for you.
bucket	no	yes	audio_summary, artist_familiarity, artist_hotttnesss, artist_location, song_hotttnesss, song_type, tracks, id:Rosetta-space	specifies which information should be returned for each matching song

You can call song/identify with GET or POST.

Identifying songs with POST

Posting tracks with /song/identify can be done in two manners

1. An HTTP POST request with Content-Type "multipart/form-data" where all parameters are in the post body and the query is in the "query" parameter of the post "files"
2. An HTTP POST request with Content-Type "application/octet-stream", with the local query file as the body of the request, and the parameters in the URL

Example POSTs:

curl -F "api_key=YOUR_API_KEY" -F "query=@json_string.json" "http://developer.echonest.com/api/v4/song/identify"

curl -X POST -H "Content-Type:application/octet-stream" "http://developer.echonest.com/api/v4/song/identify?api_key=YOUR_API_KEY" --data-binary "@json_string.json"

Identifying songs with GET

If you call song/identify with GET, you give the code parameter directly along with any metadata fields:

http://developer.echonest.com/api/v4/song/identify?api_key=YOUR_API_KEY&artist=Michael%20Jackson&title=Billie%20Jean&code=eJxVlIuNwzAMQ1fxCDL133-xo1rnGqNAEcWy_ERa2aKeZmW9ustWVYrXrl5bthn_laFkzguNWpklEmoTB74JKYZSPlbJ0sy9fQrsrbEaO9W3bsbaWOoK7IhkHFaf_ag2d75oOQSZczbz5CKA7XgTIBIXASvFi0A3W8pMUZ7FZTWTVbujCcADlQ_f_WbdRNJ2vDUwSF0EZmFvAku_CVy440fgiIvArWZZWoJ7GWd-CVTYC5FCFI8GQdECdROE20UQfLoIUmhLC7IiByF1gzbAs3tsSKctyC76MPJlHRsZ5qhSQhu_CJFcKtW4EMrHSIrpTGLFqsdItj1H9JYHQYN7W2nkC6GDPjZTAzL9dx0fS4M1FoROHh9YhLHWdRchQSd_CLTpOHkQQP3xQsA2-sLOUD7CzxU0GmHVdIxh46Oide0NrNEmjghG44Ax_k2AoDHsiV6WsiD6OFm8y-0Lyt8haDBBzeMlAnTuuGYIB4WA2lEPAWbdeOabgFN6TQMs6ctLA5fHyKMBB0veGrjPfP00IAlWNm9n7hEh5PiYYBGKQDP-x4F0CL8HkhoQnRWN997JyEpnHFR7EhLPQMZmgXS68hsHktEVErranvSSR2VwfJhQCnkuwhBUcINNY-xu1pmw3PmBqU9-8xu0kiF1ngOa8vwBSSzzNw==

Here is a sample query:

{
  "metadata": {
    "artist": "Michael jackson",
    "release": "800 chansons des annes 80",
    "title": "Billie jean",
    "genre": "",
    "bitrate": 192,
    "sample_rate": 44100,
    "duration": 294,
    "filename": "../billie_jean.mp3",
    "samples_decoded": 220598,
    "given_duration": 20,
    "version": 3.13
  },
  "code": "eJxVlIuNwzAMQ1fxCDL133-xo1rnGqNAEcWy_ERa2aKeZmW9ustWVYrXrl5bthn_laFkzguNWpklEmoTB74JKYZSPlbJ0sy9fQrsrbEaO9W3bsbaWOoK7IhkHFaf_ag2d75oOQSZczbz5CKA7XgTIBIXASvFi0A3W8pMUZ7FZTWTVbujCcADlQ_f_WbdRNJ2vDUwSF0EZmFvAku_CVy440fgiIvArWZZWoJ7GWd-CVTYC5FCFI8GQdECdROE20UQfLoIUmhLC7IiByF1gzbAs3tsSKctyC76MPJlHRsZ5qhSQhu_CJFcKtW4EMrHSIrpTGLFqsdItj1H9JYHQYN7W2nkC6GDPjZTAzL9dx0fS4M1FoROHh9YhLHWdRchQSd_CLTpOHkQQP3xQsA2-sLOUD7CzxU0GmHVdIxh46Oide0NrNEmjghG44Ax_k2AoDHsiV6WsiD6OFm8y-0Lyt8haDBBzeMlAnTuuGYIB4WA2lEPAWbdeOabgFN6TQMs6ctLA5fHyKMBB0veGrjPfP00IAlWNm9n7hEh5PiYYBGKQDP-x4F0CL8HkhoQnRWN997JyEpnHFR7EhLPQMZmgXS68hsHktEVErranvSSR2VwfJhQCnkuwhBUcINNY-xu1pmw3PmBqU9-8xu0kiF1ngOa8vwBSSzzNw=="
}

The query parameter needs to be a JSON dictionary and can accept the following fields:

metadata: a JSON dictionary containing 0 or more of the following: artist, release, title, genre, seconds, filename, version. Any other fields will be ignored.

code: required. A list of codes generated by either the Echoprint or the ENMFP code generator.

Any additional keys in the query are ignored.

Here is an example response:

{
  "response": {
    "status": {
      "code": 0,
      "message": "Success",
      "version": "4.2"
    },
    "songs": [
      {
        "title": "Billie Jean",
        "artist_name": "Michael Jackson",
        "artist_id": "ARXPPEY1187FB51DF4",
        "score": 49,
        "message": "OK (match type 5)",
        "id": "SOKHYNL12A8C142FC7"
      }
    ]
  }
}

Echo Nest Fingerprinting systems The Echo Nest current supports two music fingerprinting systems: ENMFP and Echoprint. Each system has its own licensing, speed, database size and other characteristics. Please read our up-to-date FAQ on our fingerprinting solutions.

Choose the fingerprinter that is right for your application based on the following information:

• ENMFP - The Echo Nest Musical fingerprinter is a closed source, free for use subject to the terms of the Echo Nest Terms Of Service. The ENMFP database is roughly 30,000,000 songs. The ENMFP works best on full file identification (i.e. no over-the-air recognition). The ENMFP generates fingerprint codes at about 20x real time (i.e. codegen for a 30 second audio snippet takes about 1.5 seconds). The ENMFP codegen is available for download here.
• Echoprint - The Echoprint is an open source, free for any use (including commercial) music fingerprint system. The Echoprint database is roughly 200,000 publicly available fingerprinted songs, growing soon. Echoprint works for full file identification and also supports over-the-air recognition. Echoprint generates fingerprint codes at about 1000x real time. The Echoprint codegen is available for download at echoprint.me.