Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Ruby last.fm API version v2 < HTTParty
Ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
examples
lib
test
.document
.gitignore
LICENSE
README.rdoc
Rakefile
VERSION
glutton_lastfm.gemspec

README.rdoc

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

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.

License

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

Something went wrong with that request. Please try again.