glutton_lastfm¶ ↑

Simple Ruby wrapper for the last.fm API (version 2.0) written using HTTParty.

Installation¶ ↑

sudo gem install glutton_fm

This gem is hosted at: rubygems.org/gems/glutton_lastfm

Note: A last.fm API key is also required. See: last.fm/api

Implemented Methods¶ ↑

[method invocation] => [api docs url]:

• artist_search( artist_name ) => www.last.fm/api/show/?service=272

• artist_info( artist_name ) => www.last.fm/api/show/?service=267

• artist_info_by_mbid( artist_musicbrainz_id ) => www.last.fm/api/show/?service=267

• artist_top_albums( artist_name ) => www.last.fm/api/show/?service=287

• artist_top_tracks( artist_name ) => www.last.fm/api/show/?service=277

• atrist_top_tags( artist_name ) => www.last.fm/api/show/?service=288

• artist_events( artist_name ) => www.last.fm/api/show/?service=117

• album_search( album_name, artist_name ) => www.last.fm/api/show?service=357

• album_info( album_name ) => www.last.fm/api/show?service=290

• album_info_by_mbid( album_musicbrainz_id ) => www.last.fm/api/show?service=290

Note: Not all of the last.fm API methods have been implemented. Fork this gem to implement your own using the provided q method.

Example¶ ↑

require 'rubygems'
require 'glutton_lastfm'
require 'pp'

last = GluttonLastfm.new '<your last.fm API key>'

artist = 'Green Day'

artist_search       = last.artist_search artist
artist_info         = last.artist_info artist
artist_info_by_mbid = last.artist_info_by_mbid '084308bd-1654-436f-ba03-df6697104e19'
artist_top_albums   = last.artist_top_albums artist
artist_top_tracks   = last.artist_top_tracks artist
artist_top_tags     = last.artist_top_tags artist
artist_events       = last.artist_events artist

album = 'Dookie'

album_search       = last.album_search album
album_info         = last.album_info artist, album
album_info_by_mbid = last.album_info_by_mbid '17ca17ed-f061-4d5b-97e2-848d85e47d95'

# Inspect any of the returned structures using pp (pretty print):

pp album_info

More examples can be found in the examples folder of the source repository.

Query Responses¶ ↑

Queries to glutton_lastfm methods return hierarchical hash / array strucutres. As shown above, it is best to familarize yourself with the returned data using the pp (pretty print) inspector.

Here’s a look at the returned data in a pseudo-structure. In reality all hash keys are strings.

• artist_info & artist_info_by_mbid

  artist_info{
    name
    mbid
    url
    image[]
    similar{ artist }[]{ name url image[] }
    tags{ tag }[]{ name url }
    bio{ published summary content }
  }
  

• album_info & album_info_by_mbid

  album_info{
    name
    artist
    releasedate
    url
    id
    mbid
    toptags{ tag }[]{ name url }
    image[]
    wiki{ published content summary}
  }
  

• artist_search

  artist_search[]{
    name
    url
    mbid
    image[]
  }
  

• album_search

  album_search[]{
    name
    url
    mbid
    image[]
  }
  

• artist_top_albums

  artist_top_albums[]{
    name
    mbid
    rank
    image[]
    artist{ name url mbid }
    url
  }
  

• artist_top_tracks

  artist_top_tracks[]{
    name
    artist{ name url mbid }
    url
    rank
    mbid
    image[]
  }
  

• atrist_top_tags

  artist_top_tags[]{
    name
    url
    count
  }
  

• artist_events

  artist_events[]{
    artists{ artist headliner }
    title
    url
    startDate
    id
    tags{ tag }[]
    website
    tickets
    venue{ name website location{ city country postalcode street geo:point } }
    description
    image[]
  }
  

Note: Since these objects are generated from the last.fm XML responses their structure is idiosyncratic; be cautious of inconsistencies and superfluous nesting.

Exceptions¶ ↑

The following custom exceptions may be thrown by the library:

Unauthorized

Access to the API was refused. Check your API key.

NotFound

Last.fm returned a 404 (Page Not Found) HTTP code for your request.

QueryStatusFail

Received a well-formed response but the status attribute shows that your request failed.

QueryArgumentFail

There was a problem with the parameters supplied to the API method.

UnknownFail

An unanticipated error occurred. If this happens consistently, post a GitHub project issue.

Note: If you receive a REXML::ParseException that looks like the following, then the last.fm API may be offline:

/usr/lib/ruby/1.8/rexml/parsers/baseparser.rb:330:in `pull': Missing end tag for 'HR' (got "BODY") (REXML::ParseException)

Change Log¶ ↑

• 0.1.0 - Initial release.

• 0.1.1 - Minor post-initial release patch.

• 0.1.2 - Yanked bad fix.

• 0.1.3 - Methods that return arrays (i.e. all methods other than the info ones) were fixed for result sizes of zero or one. (See: fix_empties_or_singles)

Thanks¶ ↑

Respect to the creators and maintainers of HTTParty, FakeWeb and Jeweler.

• github.com/jnunemaker/httparty

• github.com/chrisk/fakeweb

• github.com/technicalpickles/jeweler

License¶ ↑

This is free and unencumbered software released into the public domain. See LICENSE for details.