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_discovery returns the discovery score for the song's artist. This is a measure of how unexpectedly popular the artist is.
artist_discovery_rank returns the discovery rank for the song's artist
artist_familiarity returns the familiarity for the song's artist
artist_familiarity_rank returns the familiarity rank for the song's artist
artist_hotttnesss returns the hotttnesss for the song's artist
artist_hotttnesss_rank returns the hotttnesss rank for the song's artist
artist_location returns information about the location of origin for the song's artist
song_currency returns the currency score of the song. This is a measure of how recently popular the song is.
song_currency_rank returns the currency rank of the song.
song_discovery returns the discovery score of the song. This is a measure of how unexpectedly popular the song is.
song_discovery_rank returns the discovery rank of the song.
song_hotttnesss returns the hotttnesss of the song
song_hotttnesss_rank returns the hotttnesss rank of the song
song_type returns a list of song types for the song. Possible song types returned are: 'christmas', 'live' 'studio', 'acoustic', and 'electric'
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.

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 yes SOCZMFK12AC468668F the song ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
track_id yes yes 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_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 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_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 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 2,000,000 fingerprinted songs, and growing. Echoprint works for full file identification and experimentally supports over-the-air recognition (still in development). Echoprint generates fingerprint codes at about 1000x real time. The Echoprint codegen is available for download at echoprint.me.