What does this do?
Install the gem, and you're ready to go. Simply add the following to your Gemfile:
gem "genius", "~> 0.1.1"
The best way to get a decent idea of the attributes available on
the other objects is by checking out the API documentation at:
You'll need to set your access token before using the library. You can create a client and grab an access token from http://genius.com/api-clients. You can then use that like so:
Genius.access_token = 'your-access-token'
At the moment, this library isn't set up for a traditional multi-user OAuth setup - despite the Genius API being based on OAuth. It's built for the use case of just accessing the API with your account. This may change in future.
The library has one configuration option letting you choose between response formats between
dom - this is the
text_format option in the API.
It'll default to
plain, meaning you'll get back plain texts from API fields which return rich resources (artists' descriptions or annotations' contents). You can change this like so:
Genius.text_format = "html"
You can find a song by name, or using it's unique ID.
To find a song by name, use
Genius::Song.search like this:
songs = Genius::Song.search("The Hills") # Returns an array of Song objects the_hills = songs.first the_hills.title # => "The Hills" the_hills.primary_artist.name # => "The Weeknd"
Alternatively, you can find a song by it's unique ID. They're not especially easy to find, but if you hover over the "PYONG!" button near the top of the page, you'll see the song's ID in the URL. Once you have an ID, you can load a song via the API:
song = Genius::Song.find(176872) song.title # => "Versace" song.primary_artist.name # => "Migos"
Once you've found the song you're looking for, there are plenty of other useful details you can access:
song.title # => "Versace" song.url # => "http://genius.com/Migos-versace-lyrics" song.pyongs_count # => 198 song.description # => "Released in June 2013, not only did they take the beat from Soulja Boy’s OMG part 2 but they absolutely killed it."
You can find artists from their songs (e.g.
Song#primary_artist) and a couple of other places, or you can find them by their ID. As with songs, artists' IDs are pretty tricky to find, but you can get them by hovering over the "Follow" button on an artist's page on the Genius site.
the_hills = Genius::Song.find(727466) the_weeknd = the_hills.primary_artist # or... the_weeknd = Genius::Artist.find(2358)
Once you've found the artist you're looking for, you can then query its attributes:
artist.name # => "The Weeknd" artist.description # => "Abel Tesfaye (otherwise known as The Weeknd)..." # You can even find the artist's songs with the #songs method artist.songs # => [<Genius::Song...]
You can access your user profile with the
me = Genius::Account.me
From there, you can get access to a range of attributes:
me.name # => "timrogers" me.iq # => 1691
If you'd like to contribute anything else, go ahead or better still, make an issue and we can talk it over and spec it out! A few quick tips:
- Don't update the version numbers before your pull request - I'll sort that part out for you.
- Make sure you write specs, then run them with
$ bundle exec rake. When running tests, you'll want to set
GENIUS_ACCESS_TOKENso your requests can be authenticated - don't worry, your token will be filtered out of the
- Update this README.md file so I, and users, know how your changes work
Copyright (c) 2015 Tim Rogers. See LICENSE for details.
Get in touch
Any questions, thoughts or comments? Email me at email@example.com or create an issue.