The Echowrap Ruby Gem

A Ruby interface to the Echonest API. The Echonest API is based on their automatically derived-database of about 30 million songs which is aggregated using web crawling, data mining, and digital signal processing techniques. The API includes support for music recommendation, artist recommendation, playlist generation, acoustic analysis, music identification, and data feeds. Details about the API can be found at http://developer.echonest.com/

This wrapper 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"

Supported Rubies

This library is tested against the following Ruby implentations

Ruby 1.9.2
Ruby 1.9.3
Ruby 2.0
JRuby 1.9 mode

Gem Dependencies

Installing this gem also installs the following gems:

faraday HTTP client lib that provides a common interface over many adapters (such as Net::HTTP) and embraces the concept of Rack middleware when processing the request/response cycle.
multi_json A common interface to multiple JSON libraries, including Oj, Yajl, the JSON gem (with C-extensions), the pure-Ruby JSON gem, NSJSONSerialization, gson.rb, JrJackson, and OkJson.
simple_oauth Builds and verifies OAuth headers

Installation

Add this line to your application's Gemfile:

    gem 'echowrap'

And then execute:

    $ bundle install

Or install it yourself as:

    $ gem install echowrap

Quick Start Guide

First, get an api key from Echonest.

Then copy and paste in your API keys:

Echowrap.configure do |config|
  config.api_key =       'YOUR_API_KEY'
  config.consumer_key =  'YOUR_CONSUMER_KEY'
  config.shared_secret = 'YOUR_SHARED_SECRET'
end

If you are using Echowrap with a Rails application then a good location for the key would be to create an initializer, for example you could place the above code in /config/initializers/echowrap.rb.

You can also use Echowrap in any plain old ruby file and I've included an example of this here

You are ready to use Echowrap:

Echowrap.song_search(artist: 'Daft Punk')

Usage

See Usage page for a complete listing of the api methods

Tests

An Rspec test suite is available to ensure API functionality:

$ git clone git://github.com/timcase/echowrap.git
$ bundle install (installs rspec and other supporting gems, see GEMFILE for complete listing)
$ rspec

More Information

More information can be found on the project website on GitHub. There is extensive usage documentation available on the wiki.

API Documentation

Full API Documentation can be found in the wiki

License

Echowrap is released under the MIT License.

Support

Bug reports and feature requests should be filed on the github issue tracking page.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

##Acknowledgement Much of the heavy lifting was done by studying the Twitter gem.

##Contributors Tim Case

timcase/echowrap