official.fm

Ruby wrapper for the official.fm v2 API.

Installation

gem install officialfm

Alternatively put this in you Gemfile, then run bundle install:

gem 'officialfm'

Get your API key

Coming soon.

You can also access the API without an API key, but with a lower rate limit.

Client instantiation and configuration

Include the relevant files

require 'officialfm'

Instantiate a client

officialfm = OfficialFM::Client.new

With an API key:

officialfm = OfficialFM::Client.new(api_key: 'your_api_key')

You can also set a default configuration for all clients to use

OfficialFM.configure do |c|
  c.api_key = YOUR_API_KEY
end

Response format

All methods return a Hashie:Mash. That means you can access the response fields via method-like accessors. For example:

search_results = officialfm.tracks('Wiz Khalifa')
track = search_results[3].track
puts "#{track.title} by #{track.artist}"

API response enhancements

The API wraps responses in a root element, e.g.:

{
  "track": {
    "title": "Some track"
    ...
  }
}

The responses given by methods in the gem don't have a root and expose the resource's properites directly instead (e.g. officialfm.track('xxxx').title).

Search results are also unwrapped. For example, the raw response of a track search looks like:

{
  "page": 1,
  "total_entries": 2,
  "total_pages": 1,
  "tracks" : [
    {
      "track": {
         // track properties
      }
    },
    {
      "track": {
         // track properites
      }
    }
  ]
}

The gem removes the roots of the search result items, so you can access an item directly through array access.

track = officialfm.tracks('foo').tracks[0]
puts track.duration

Methods

Tracks

Search for a track:

officialfm.tracks('Nightcall')

Search results being paged, you can request a specific page with the page parameter.

officialfm.tracks('Kids', page: 2)

Filter results by track type (original, remix, cover, mashup, mixtape):

officialfm.tracks('Mac Miller', types: ['original', 'remix'])

Get info about a specific track:

officialfm.track('1nnQ')

Get the artwork and streaming urls

officialfm.track('1nnQ', fields: ['cover', 'streaming'])

Playlists

Search for a playlist (again you can pass an optional page parameter to get a specific results page):

officialfm.playlists('AWOLNATION')

Get info about a specific playlist:

officialfm.playlist('CbqY')

Retrieve the tracks in a playlist:

playlists = officialfm.playlists('AWOLNATION')

# The tracks for the 3 playlist in the search results
tracks = playlists[2].tracks

Note that the tracks method of a playlist object makes an extra request. If you know the playlist ID in advance, you can retrieve the tracks in just one request.

officialfm.playlist_tracks('CbqY')

Projects

Search for a project (a project can be an artist or a collaboration between several artists)

officialfm.projects('Mac Miller x Pharrell')

Similarly to playlists, you can get information about a specific project with

officialfm.project('edB6')

Get a project's tracks or playlists when you know the project ID in advance.

tracks = officialfm.project_tracks('edB6')
playlists = officialfm.project_playlists('edB6')
puts artist.tracks
puts artist.playlists

Of course you can get the playlists and tracks in a project even if you don't know its ID:

projects = officialfm.projects('Mac Miller')

puts projects[0].name # => 'Mac Miller'
puts projects[2].name # => 'Mac Miller x Pharrell'

tracks = projects[2].tracks