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.
License¶ ↑
This is free and unencumbered software released into the public domain. See LICENSE for details.