A Ruby interface to The Echo Nest API

   Quick Start    Demos   About   Github Source   Docs

The Echo Nest is the world’s leading music intelligence company. They provide the largest repository of dynamic music data in the world – over a trillion data points on over 30 million songs -- to help application developers build smarter music apps.

Echowrap provides a Ruby interface to The Echo Nest API:

  • Echowrap supports 100% of the Echonest API Version 4
  • Data returned from API calls are mapped into Ruby objects
  • Various http clients are supported via Faraday
  • Uses Unix philosophy of "do one thing and do it well"

Some things you can do via the API

  • Analyze a track to find it's key, energy level, danceability, acousticness, and whether it's live or studio
  • Break down a track by it's sections, beats, and fractions of a beat
  • Identify an unknown piece of music
  • Search for artists using a wide variety of criteria and get in-depth info about an artist:
    • The artist's location
    • Blogs associated witht the artist
    • The artist Bio
    • Numerical rating of how familiar the artist is
    • Numerical rating of how "hot" the artist is
    • News associated with the artist
    • Reviews of work by the artist
    • List songs by the artist
    • Find other similar artists to a particular artist
    • The artist's twitter feed
    • Videos of the artist
    • Notable url related to artist
  • Create taste profiles to track what you like
  • Find more music that you may like based on your taste profile
  • Create playlists based on your tastes


  1. Create an account at Echonest click here to go the Echonest API Signup page.
  2. Activate your Echonest account by clicking the link in the Activation email you should receive.
  3. You will see your account is activated, and you should see your API Key, Consumer Key, and Shared Secret. Initial API request limit is 10 API calls per hour.
  4. $ gem install echowrap
  5. $ irb
  6. > require 'echowrap'
             => true
  7. > Echowrap.configure do |config|
        config.api_key = 'YOUR API KEY'
        config.consumer_key = 'YOUR CONSUMER KEY'
        config.shared_secret = 'YOUR SHARED SECRET'
    => Echowrap
  8. Echowrap.artist_search(:name => 'daft', :results => 3)
               => [#"Daft Punk", :id=>"ARF8HTQ1187B9AE693"}>, 
                   #"Daft Punk+Fool", :id=>"ARPNDFM13E43CE6D63"}>, 
                   #"Daft Punk/Avicii", :id=>"ARPKVEU136F6F0CD19"}>]


Find Artist
ex. Lana Del Rey, Phoenix, R. Kelly

  def find_artist
    @artist = Echowrap.artist_search(:name => params[:artist_name], 
                                     :results => 1, 
                                     :bucket => ['hotttnesss', 'familiarity', 'artist_location'])
Find Similar Artists
ex. AC/DC, Macklemore, Vampire Weekend
  def find_similar
    @artists = Echowrap.artist_similar(:name => params[:artist_name], :bucket => ['artist_location', 'hotttnesss'])
    @artists = @artists.sort{|a, b| a.hotttnesss <=> b.hotttnesss}.reverse
Find Artist's Songs
ex. Daft Punk, Radiohead, Kendrick Lamar
  def find_songs
    @songs = Echowrap.artist_songs(:name => params[:artist_name])
Find Artist's images
ex. LCD Soundsystem, Empire of the Sun, Eminem
  def find_images
    @images = Echowrap.artist_images(:name => params[:artist_name])


Echowrap was built by Tim Case, who likes building audio projects both software and hardware.

He plays music under the moniker Blastin Martin.