hits counter

Brian Whitman @ variogr.am Brian Whitman @ variogr.am

Scroll to Info & Navigation

Primer on new Echo Nest search_tracks, capsule, and get_analysis APIs

Note: if you are interested in these APIs know that they are no longer alpha — see our new Song APIs for the latest information. At Stockholm Hack Day we’re announcing three or four new APIs that are going to stay in our “alpha” sandbox for now. These are officially unsupported but we will work with anyone who has a use case for them. For now, the instructions will stay here until we promote them to production APIs.

For all of these alpha APIs you will need a developer key from The Developer Nest. I will use “YOUR_KEY” as the key in the examples, make sure to replace this or none of the calls will work. We reserve the right to pull or throttle access to alpha APIs at a different rate from the supported ones. Please be warned that these are not production ready, we will be making enhancements and restarting servers, there will be guaranteed downtime. If you are interested in building a product with these new APIs please contact us..

capsule

What: returns a rendered mp3 and swf url given an XSPF playlist that is composed of a “megamix” or “jam" of the included tracks in order.

How:

http://developer.echonest.com/api/alpha_capsule?api_key=YOUR_KEY&xspf_url=http://path_to.com/playlist.xspf

Returns

{'flash_url': 'http://thisismyjam.com/flash/jam.swf?api_PNWUcuxGJ5/1264353117.xml', 
'tag': 'api_PNWUcuxGJ5', 
'mp3_url': 'http://echonest-capsule.s3.amazonaws.com/api_PNWUcuxGJ5/1264353117.mp3'}

Parameters:

  • api_key - your developer nest key. Required
  • xspf_url - a resolvable url to an XSPF file. Required.
  • tag - string to use instead of randomly generated.
  • transition - in seconds, length of transition
  • duration - in seconds, length of each song playback

Returns:

  • flash_url - a url to a flash player similar to This is My Jam
  • mp3_url - a url to a playable mp3 file
  • tag - code used to check for existence of capsule.

Notes:

  • Capsules take time to render. An average 10 song capsule with the default transition and duration will take 45 seconds. To see if the capsule is ready, you can test the mp3_url for a status code. 403 means it is not ready. 200 means it is.

get_analysis

DEPRECATED 4/23/10 — GO HERE

What: returns the entire analysis for an Echo Nest track ID. (more ID types to come soon.) Saves multiple calls (get_segments, get_tempo, etc etc) and allows you to get the analysis of tracks you did not upload (after finding them with search_tracks.)

How:

DEPRECATED 4/23/10 — use songs/search with the audio_summary bucket to get the full analysis for a song
http://developer.echonest.com/api/alpha_get_analysis?api_key=YOUR_KEY&trackID=TRMAOUK1254889A145

Returns

{"status": "OK", "analysis": 
	{"bars": [{"duration": 0.75963000000000003, "start": 0.37046000000000001, 
	...

Parameters:

  • api_key - your developer nest key. Required
  • trackID - an Echo Nest track ID starting with TR. Required

Returns:

  • analysis - the entire Echo Nest audio analysis in json.

Notes:

  • The json responses are large. Be careful.

search_tracks

DEPRECATED 4/23/10 — use songs/search for this

What: Given a number of possible query types return a list of matching tracks that The Echo Nest maintains. Search on metadata (artist, title), audio data (tempo, duration, loudness, key, mode, etc), cultural data (automatically computed tags, aka “topterms”, familiarity and hotttnesss, collated edited style and genre classifications, etc.) and even location data (latitude / longitude of artist origin.)

How:

DEPRECATED 4/23/10 — GO HERE
Look for a song:
http://developer.echonest.com/api/alpha_search_tracks?api_key=YOUR_KEY&title=My%20Sound&artist=Squarepusher

Get the loudest romantic song:
http://developer.echonest.com/api/alpha_search_tracks?api_key=YOUR_KEY&query=romantic&sort=-loudness&results=1

Get the songs between two tempos:
http://developer.echonest.com/api/alpha_search_tracks?api_key= YOUR_KEY&constraint_tempo_min=120&constraint_tempo_max=125&artist=Squarepusher


Returns
{"status": "ok", "results": 
	[{"trackID": "TRMAOUK1254889A145", "title": "Dream On", "artist": "Aerosmith"},
	...

Parameters:

  • api_key - your developer nest key. Required
  • title - Song title
  • artist - Artist name
  • query - Full text query of description (“funky jazz”, “romantic”, “heavy metal”)
  • results - number of results to return, maximum 100, default 20
  • constraint_tempo_max - Maximum tempo in beats per minute
  • constraint_tempo_min - Minimum tempo in beats per minute
  • constraint_duration_max - Maximum duration in seconds
  • constraint_duration_min - Minimum duration in seconds
  • constraint_loudness_max - Maximum average song loudness in dB
  • constraint_loudness_min - Minimum average song loudness in dB
  • constraint_familiarity_max - Maximum artist familiarity
  • constraint_familiarity_min - Minimum artist familiarity
  • constraint_hotttnesss_max - Maximum artist hotttnesss
  • constraint_hotttnesss_min - Minimum artist hotttnesss
  • constraint_mode - Only allow major (1) or minor (0) modes in results
  • constraint_key - Only allow key (0-11, C to B) in results
  • constraint_latitude_min, constraint_longitude_min, constraint_latitude_max, constraint_longitude_max - Only allow these locations in results
  • sort - sort results by parameter: for example &sort=-tempo will sort by tempo decreasing. &sort=+tempo will sort by tempo increasing. &sort=-longtiude will sort by longitude decreasing. Also supported: latitude, key, mode, loudness, duration, familiarity, hotttnesss.

Returns:

  • trackID - the Echo Nest track ID.
  • artistID - the Echo Nest artist ID (for use with other EN APIs
  • artist, title - track metadata
  • tempo, duration, mode, loudness, key - if used as a sort or constraint these parameters will appear in results as well per track. Otherwise you can use get_analysis.

Notes:

  • This is a heavily alpha API that will have some serious issues but we welcome all feedback.
  • Textual queries do not return their matching terms in results
  • Geographic queries do not return their matching locations in results
  • If you put a + sign (%2B) in front of an artist or title it will force a match, otherwise it won’t. You can use quotes in artist, title and query parameters for proximity, aka artist=”Britney Spears”

identify_track

DEPRECATED 4/23/10 — use songs/alpha_identify_song

What: Returns metadata for a track given Echo Nest Musical Fingerprint hash codes.

Notes:

  • Not currently public. Talk to Brian for access to the code generator and API.