Skip to content

Latest commit

 

History

History
153 lines (98 loc) · 5.3 KB

README.md

File metadata and controls

153 lines (98 loc) · 5.3 KB
Raw

Genius

Build Status Gem Version

Genius logo

What does this do?

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

Installation

Install the gem, and you're ready to go. Simply add the following to your Gemfile:

gem "genius", "~> 0.1.2"

Usage

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

Authentication

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.

Configuration

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"

Songs

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.

Artist

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.

Account

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.

Other resources

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

Contributing

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

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

Get in touch

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