This is a Java API and assorted tools and helpers for the Echo Nest API (at developer.echonest.com).

Table of Contents

• The Echo Nest API Overview
• Getting Started
• Code Examples
• Running the examples

The Echo Nest API Overview

The Echo Nest API is divided into two sets of methods: Artist methods and track methods.

Artist Methods

Some of the Echo Nest artist capabilities:

• get a list of the hottest artists
• search for artists
• get news about an artist
• get reviews about an artist
• get blogs about an artist
• get urls for an artist
• get video for an artist
• find audio for an artist
• find familiarity and hotttness of an artist

Track methods

Some of the Echo Nest track capabilities:

• Upload a track for analysis
• Get metadata for a track
• get the overall key of a track
• Get the overall loudness of a track
• Get the overall time signature of a track
• Get the overall tempo of a track
• Get the duration of a track
• Get the mode (major/minor) of a track
• Get the fade-in and fade-out times for a track
• Get a detailed analysis of the beat structure of a song including sections, bars, beats and tatums
• Get timbral, pitch and loudness information for every sound event in the track

Getting Started

• Download the latest release
• Unzip the archive
• Add the EchoNestAPI.jar file to your CLASSPATH
• Browse some of the code samples
• Get an API key from developer.echonest.com
• Browse the Javadocs included with the distribution

Code Examples

Artist Similarity Example

Here's an example of code to print out all artists that are similar to 'Weezer'

   ArtistAPI artistAPI = new ArtistAPI(MY_ECHO_NEST_API_KEY);

   List<Artist> artists = artistAPI.searchArtist("weezer", false);

   for (Artist artist : artists) {
        List<Scored<Artist>> similars = artistAPI.getSimilarArtists(artist, 0, 10);
        for (Scored<Artist> simArtist : similars) {
            System.out.println("   " + simArtist.getItem().getName());
        }
    }
  

Artist Audio example

Use the Echo Nest Artist API to find audio for an artist

   ArtistAPI artistAPI = new ArtistAPI(MY_ECHO_NEST_API_KEY);

   List<Artist> artists = artistAPI.searchArtist("The Decemberists", false);
   for (Artist artist : artists) {
       DocumentList<Audio> audioList = artistAPI.getAudio(artist, 0, 15);
       for (Audio audio : audioList.getDocuments()) {
          System.out.println(audio.toString());
       }
   }

Track BPM example

Here's some sample code to determine the average BPM for a track:

    TrackAPI trackAPI = new TrackAPI(MY_ECHO_NEST_API_KEY);

    String id = trackAPI.uploadTrack(new File("/path/to/music/track.mp3"), false);
    AnalysisStatus status = trackAPI.waitForAnalysis(id, 60000);
    if (status == AnalysisStatus.COMPLETE) {
       System.out.println("Tempo in BPM: " + trackAPI.getTempo(id));
    }                 

Running the examples

FindSimilarArtists

 $ java -DECHO_NEST_API_KEY=$MY_ECHO_NEST_KEY -cp EchoNestAPI.jar  examples.FindSimilarArtists 'weezer' 
---- Similar artists for Weezer ---- 
    Nerf Herder
    The Smashing Pumpkins
    Third Eye Blind
    Ozma
    Fountains of Wayne
    Nada Surf
    Ben Folds Five
    The Flaming Lips
    Jimmy Eat World
    Death Cab for Cutie
    Veruca Salt
    Sunny Day Real Estate
    They Might Be Giants
    Alkaline Trio
    Rivers Cuomo
 

FindArtistAudio

 $ java -DECHO_NEST_API_KEY=$MY_ECHO_NEST_KEY -cp EchoNestAPI.jar  examples.FindArtistAudio 'The Decemberists' 
 ---- Audio for The Decemberists ----
 artist: The Decemberists
 artist_id: music://id.echonest.com/~/AR/ARHWR8B1187FB557D3
 length: 195.0
 link: http://theyellowstereo.com/2009/03/the-daily-graboid-69/ release: The Hazards Of Love 
 title: The Rake's Song
 url: http://www.theyellowstereo.com/Daily%20Graboid/week2/The%20Decemberists%20-%20The%20Rake%27s%20Song.mp3 
artist: The Decemberists
 artist_id: music://id.echonest.com/~/AR/ARHWR8B1187FB557D3
 length: 299.0
 link: http://passionweiss.com release: Always The Bridesmaid: A Singles Series
 title: Valerie Plame
 url: http://passionweiss.com/wp-content/uploads/2008/12/01-valerie-plame.mp3 
(entries omitted) 

The debug shell

The API also includes an interactive shell that lets you easily interact with the Echo Nest API. Some examples:

 java -DECHO_NEST_API_KEY=$MY_ECHO_NEST_KEY -cp EchoNestAPI.jar  com.echonest.api.v3.test.EchonestDevShell 
nest% search_artist blitzen 
music://id.echonest.com/~/AR/ARMT1QJ1187FB3D555 Blitzen
 music://id.echonest.com/~/AR/ARKHKCO1187FB429D0 Rudolph & Blitzen
 music://id.echonest.com/~/AR/ARJ3IUO1187B999C26 Donner & Blitzen
 music://id.echonest.com/~/AR/ARXWFZ21187FB43A0B Blitzen Trapper
 
nest% get_audio blitzen trapper 
Audio for Blitzen Trapper
 Total audio 107
 id: 9b634d44a89839038a8fc30b0dcc03a9 type: audio
   title: Texaco
   artist: Blitzen Trapper
   artist_id: music://id.echonest.com/~/AR/ARXWFZ21187FB43A0B
   release: Dead Bees Label Sampler #2
   url: http://media.deadbees.com/sampler_02/Dead%20Bees%20Sampler%202%20-%2003%20-%20Blitzen%20Trapper%20-%20Texaco.mp3 
(etc) 
nest% trackUpload /Users/plamere/Music/Amazon MP3/The Decemberists/Hazards Of Love/13 - Annan Water.mp3 
ID: music://id.echonest.com/~/TR/TRINNMV1208142F431
 
nest% trackMetadata music://id.echonest.com/~/TR/TRINNMV1208142F431 
Artist    : The Decemberists
 Release   : Hazards Of Love
 Title     : Annan Water
 Genre     : Pop
 Duration  : 311.4291
 Samplerate: 44100
 Bitrate   : 263
 
nest% trackTempo music://id.echonest.com/~/TR/TRINNMV1208142F431 
101.963 (0.444)
 
nest% help 
(shows you the 60 or so available commands)