Genius

It's a Ruby gem for accessing songs, artists and annotations on Genius, based on the original rapgenius gem.

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 Song and the other objects is by checking out the API documentation at: https://docs.genius.com

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 plain, html and 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."

Check out song.rb or the Genius API documentation for a full list of available fields.

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...]

Check out artist.rb or the Genius API documentation for a full list of available fields.

You can access your user profile with the Genius::Account.me method:

me = Genius::Account.me

From there, you can get access to a range of attributes:

me.name
# => "timrogers"

me.iq
# => 1691

Check out account.rb or the Genius API documentation for a full list of available fields.

The API library also supports working with web pages, annotations and referents in the API. See the Genius API documentation and the library source.

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_TOKEN so your requests can be authenticated - don't worry, your token will be filtered out of the vcr cassettes.
• Update this README.md file so I, and users, know how your changes work

Copyright (c) 2015 Tim Rogers. See LICENSE for details.

Any questions, thoughts or comments? Email me at me@timrogers.co.uk or create an issue.