Project

officialfm

0.0
No commit activity in last 3 years
No release in over 3 years
Official Ruby bindings for the official.fm v2 API
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 1.0
~> 0.8
~> 2.11
~> 2.1

Runtime

~> 0.8.1
~> 1.2
 Project Readme

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

Copyright

Copyright (c) 2012 official.fm