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.