Skip to content

Latest commit

 

History

History
162 lines (130 loc) · 5 KB

README.rdoc

File metadata and controls

162 lines (130 loc) · 5 KB
Raw

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. 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.

Thanks ↑

Respect to the creators and maintainers of HTTParty and Jeweler.

License ↑

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