rscrobbler 0.1.0 → 0.2.0

data/lib/lastfm/api/track.rb

@@ -0,0 +1,272 @@
+module LastFM
+  module Api
+    class Track
+      class << self
+
+        # Add a list of user supplied tags to a track.
+        #
+        # @option params [String, required] :artist   the artist name
+        # @option params [String, required] :track    the track name
+        # @option params [Array,  required] :tags     array of tags to apply to this track. accepts a maximum of 10.
+        # @see http://www.last.fm/api/show?service=304
+        def add_tags( params )
+          LastFM.requires_authentication
+          LastFM.post( "track.addTags", params )
+        end
+
+        # Ban a track for the current user.
+        #
+        # @option params [String, required] :artist   the artist name
+        # @option params [String, required] :track    the track name
+        # @see http://www.last.fm/api/show?service=261
+        def ban( params )
+          LastFM.requires_authentication
+          LastFM.post( "track.ban", params )
+        end
+
+        # Get a list of buy Links for a track.
+        #
+        # @option params [String,  required unless :mbid] :artist         the artist name
+        # @option params [String,  required unless :mbid] :track          the track name
+        # @option params [String,  required]              :country        a country name, as defined by ISO 3166-1
+        # @option params [String,  optional]              :mbid           the musicbrainz id for the track
+        # @option params [Boolean, optional]              :autocorrect    correct misspelled artist and track names to be returned in the response
+        # @return [Array<LastFM::Buylink>] collection of links where this track can be bought or downloaded
+        # @see http://www.last.fm/api/show?service=431
+        def get_buylinks( params )
+          xml = LastFM.get( "track.getBuylinks", params )
+          [:physical, :download].each_with_object([]) do |type, buylinks|
+            xml.find("affiliations/#{type}s/affiliation").each do |buylink|
+              buylinks << LastFM::Buylink.from_xml( buylink, :type => type )
+            end
+          end
+        end
+
+        # Use the last.fm corrections data to check whether the supplied track has a correction to a canonical track
+        #
+        # @option params [String, required] :artist   the artist name to correct
+        # @option params [String, required] :track    the track name to correct
+        # @see http://www.last.fm/api/show?service=447
+        def get_correction( params )
+          LastFM.get( "track.getCorrection", params )
+        end
+
+        # Retrieve track metadata associated with a fingerprint id generated by the Last.fm Fingerprinter.
+        # Returns track elements, along with a 'rank' value between 0 and 1 reflecting the confidence for
+        # each match.
+        #
+        # @option params [String, required] :fingerprint_id   the fingerprint id to look up
+        # @see http://www.last.fm/api/show?service=441
+        # @see https://github.com/lastfm/Fingerprinter
+        # @see http://blog.last.fm/2010/07/09/fingerprint-api-and-app-updated
+        def get_fingerprint_metadata( params )
+          LastFM.get( "track.getFingerPrintMetadata", params )
+        end
+
+        # Get the metadata for a track.
+        #
+        # @option params [String,  required unless :mbid] :artist         the artist name
+        # @option params [String,  required unless :mbid] :track          the track name
+        # @option params [String,  optional]              :mbid           the musicbrainz id for the track
+        # @option params [Boolean, optional]              :autocorrect    correct misspelled artist and track names to be returned in the response
+        # @option params [String,  optional]              :username       username whose playcount for, and whether they've loved, this track is to be returned in the reponse
+        # @return [LastFM::Track] track constructed from the metadata contained in the response
+        # @see http://www.last.fm/api/show?service=356
+        def get_info( params )
+          xml = LastFM.get( "track.getInfo", params )
+          LastFM::Track.from_xml( xml )
+        end
+
+        # Get shouts for a track.
+        #
+        # @option params [String,  required unless :mbid] :artist         the artist name
+        # @option params [String,  required unless :mbid] :track          the track name
+        # @option params [String,  optional]              :mbid           the musicbrainz id for the track
+        # @option params [Boolean, optional]              :autocorrect    correct misspelled artist and track names to be returned in the response
+        # @option params [Fixnum,  optional]              :page           the page number to fetch. defaults to first page
+        # @option params [Fixnum,  optional]              :limit          the number of results to fetch per page. defaults to 50
+        # @return [Array<LastFM::Shout>] collection of shouts
+        # @see http://www.last.fm/api/show?service=453
+        def get_shouts( params )
+          xml = LastFM.get( "track.getShouts", params )
+          xml.find('shouts/shout').map do |shout|
+            LastFM::Shout.from_xml( shout )
+          end
+        end
+
+        # Get similar tracks for a track on Last.fm, based on listening data.
+        #
+        # @option params [String,  required unless :mbid] :artist         the artist name
+        # @option params [String,  required unless :mbid] :track          the track name
+        # @option params [String,  optional]              :mbid           the musicbrainz id for the track
+        # @option params [Boolean, optional]              :autocorrect    correct misspelled artist and track names to be returned in the response
+        # @option params [Fixnum,  optional]              :limit          the number of results to fetch. defaults to 50
+        # @return [Array<LastFM::Track>] similar tracks, ordered by similarity
+        # @see http://www.last.fm/api/show?service=319
+        def get_similar( params )
+          xml = LastFM.get( "track.getSimilar", params )
+          xml.find('similartracks/track').map do |track|
+            LastFM::Track.from_xml( track )
+          end
+        end
+
+        # Get the tags on a track.
+        #
+        # @option params [String,  required unless :mbid] :artist         the artist name
+        # @option params [String,  required unless :mbid] :track          the track name
+        # @option params [String,  optional]              :mbid           the musicbrainz id for the track
+        # @option params [Boolean, optional]              :autocorrect    correct misspelled artist and track names to be returned in the response
+        # @option params [String,  optional]              :user           if called in non-authenticated mode you must specify the user to look up
+        # @see http://www.last.fm/api/show?service=320
+        def get_tags( params )
+          secure = !params.include?(:user)
+          LastFM.requires_authentication if secure
+          LastFM.post( "track.getTags", params, secure )
+        end
+
+        # Get the top fans for a track, based on listening data.
+        #
+        # @option params [String,  required unless :mbid] :artist         the artist name
+        # @option params [String,  required unless :mbid] :track          the track name
+        # @option params [String,  optional]              :mbid           the musicbrainz id for the track
+        # @option params [Boolean, optional]              :autocorrect    correct misspelled artist and track names to be returned in the response
+        # @see http://www.last.fm/api/show?service=312
+        def get_top_fans( params )
+          LastFM.get( "track.getTopFans", params )
+        end
+
+        # Get the top fans for a track, ordered by tag count.
+        #
+        # @option params [String,  required unless :mbid] :artist         the artist name
+        # @option params [String,  required unless :mbid] :track          the track name
+        # @option params [String,  optional]              :mbid           the musicbrainz id for the track
+        # @option params [Boolean, optional]              :autocorrect    correct misspelled artist and track names to be returned in the response
+        # @return [Array<LastFM::Tag>] list of tags ordered by popularity
+        # @see http://www.last.fm/api/show?service=289
+        def get_top_tags( params )
+          xml = LastFM.get( "track.getTopTags", params )
+          xml.find('toptags/tag').map do |tag|
+            LastFM::Tag.from_xml( tag )
+          end
+        end
+
+        # Love a track for the current user.
+        #
+        # @option params [String, required] :artist   the artist name
+        # @option params [String, required] :track    the track name
+        # @see http://www.last.fm/api/show?service=260
+        def love( params )
+          LastFM.requires_authentication
+          LastFM.post( "track.love", params )
+        end
+
+        # Remove a user's tag from a track.
+        #
+        # @option params [String, required] :artist   the artist name
+        # @option params [String, required] :track    the track name
+        # @option params [String, required] :tag      a single user tag to remove from this track
+        # @see http://www.last.fm/api/show?service=316
+        def remove_tag( params )
+          LastFM.requires_authentication
+          LastFM.post( "track.removeTag", params )
+        end
+
+        # Used to add a track-play to a user's profile. Scrobble a track, or a batch of tracks.
+        # Single tracks may be passed using the Object types listed, batches of tracks must be
+        # passed in as Arrays of each Object type. Allows up to a maximum of 50 scrobbles per
+        # batch. For batch scrobbles, Array indices of optional parameters must line up with
+        # the indicies of their corresponding tracks.
+        #
+        # @option params [String,  required unless :mbid] :artist           artist name
+        # @option params [String,  required unless :mbid] :track            track name
+        # @option params [String,  optional]              :mbid             the musicbrainz id for the track
+        # @option params [Time,    optional]              :timestamp        time the track started playing
+        # @option params [String,  optional]              :album            album name
+        # @option params [String,  optional]              :album_artist     album artist, if this differend from the track artist
+        # @option params [Fixnum,  optional]              :track_number     track number of the track on the album
+        # @option params [Fixnum,  optional]              :duration         track length, in seconds
+        # @option params [String,  optional]              :stream_id        track stream id, received from the radio.getPlaylist service
+        # @option params [Boolean, optional]              :chosen_by_user   whether or not the user chose the track
+        # @option params [String,  optional]              :context          sub-client version (not public, only enabled for certain api keys)
+        # @see http://www.last.fm/api/show?service=443
+        def scrobble( params )
+          LastFM.requires_authentication
+          # Tracks are passed to the service using array notation for each of the above params
+          array_params = {}
+          params.each do |hkey, hval|
+            hval = hval.to_i if hval.is_a?(Time)
+            Array(hval).each_with_index do |aval, index|
+              array_params["#{hkey}[#{index}]"] = aval
+            end
+          end
+          LastFM.post( "track.scrobble", array_params )
+        end
+
+        # Search for a track by track name. Returns track matches sorted by relevance.
+        #
+        # @option params [String, required] :track    the track name
+        # @option params [String, optional] :artist   narrow results based on an artist
+        # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+        # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+        # @return [Array<LastFM::Track>] list of tracks sorted by relevance
+        # @see http://www.last.fm/api/show?service=286
+        def search( params )
+          xml = LastFM.get( "track.search", params )
+          xml.find('results/trackmatches/track').map do |track|
+            LastFM::Track.from_xml( track )
+          end
+        end
+
+        # Share a track twith one or more Last.fm users or other friends.
+        #
+        # @option params [String,  required] :artist      the artist name
+        # @option params [String,  required] :track       the track name
+        # @option params [Array,   required] :recipient   a list of email addresses or Last.fm usernames. maximum is 10
+        # @option params [String,  optional] :message     an optional message to send. if not supplied a default message will be used
+        # @option params [Boolean, optional] :public      optionally show in the sharing users activity feed. defaults to false
+        # @see http://www.last.fm/api/show?service=305
+        def share( params )
+          LastFM.requires_authentication
+          LastFM.post( "track.share", params )
+        end
+
+        # Unban a track for the current user.
+        #
+        # @option params [String, required] :artist   the artist name
+        # @option params [String, required] :track    the track name
+        # @see http://www.last.fm/api/show?service=449
+        def unban( params )
+          LastFM.requires_authentication
+          LastFM.post( "track.unban", params )
+        end
+
+        # Unlove a track for the current user.
+        #
+        # @option params [String, required] :artist   the artist name
+        # @option params [String, required] :track    the track name
+        # @see http://www.last.fm/api/show?service=440
+        def unlove( params )
+          LastFM.requires_authentication
+          LastFM.post( "track.unlove", params )
+        end
+
+        # Used to notify Last.fm that a user has started listening to a track.
+        #
+        # @option params [String,  required unless :mbid] :artist           artist name
+        # @option params [String,  required unless :mbid] :track            track name
+        # @option params [String,  optional]              :mbid             the musicbrainz id for the track
+        # @option params [String,  optional]              :album            album name
+        # @option params [String,  optional]              :album_artist     album artist, if this differend from the track artist
+        # @option params [Fixnum,  optional]              :track_number     track number of the track on the album
+        # @option params [Fixnum,  optional]              :duration         track length, in seconds
+        # @option params [String,  optional]              :context          sub-client version (not public, only enabled for certain api keys)
+        # @see http://www.last.fm/api/show?service=454
+        def update_now_playing( params )
+          LastFM.requires_authentication
+          LastFM.post( "track.updateNowPlaying", params )
+        end
+
+      end
+    end
+  end
+end

data/lib/lastfm/api/user.rb

@@ -0,0 +1,266 @@
+module LastFM
+  module Api
+    class User
+      class << self
+
+        # Get a list of tracks by a given artist scrobbled by this user,
+        # including scrobble time. Can be limited to specific timeranges,
+        # defaults to all time.
+        #
+        # @option params [String, required] :user             last.fm username to fetch the recent tracks for
+        # @option params [String, required] :artist           the artist name to fetch tracks for
+        # @option params [Time,   optional] :startTimestamp   a unix timestamp to start at
+        # @option params [Time,   optional] :endTimestamp     a unix timestamp to end at
+        # @option params [Fixnum, optional] :page             the page number to fetch. defaults to first page
+        # @see http://www.last.fm/api/show?service=432
+        def get_artist_tracks( params )
+          LastFM.get( "user.getArtistTracks", params )
+        end
+
+        # Get a list of tracks banned by a user.
+        #
+        # @option params [String, required] :user     last.fm username
+        # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+        # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=448
+        def get_banned_tracks( params )
+          LastFM.get( "user.getBannedTracks", params )
+        end
+
+        # Get a list of upcoming events that this user is attending.
+        #
+        # @option params [String,  required] :user            last.fm username
+        # @option params [Boolean, optional] :festivalsonly   whether only festivals should be returned, or all events
+        # @option params [Fixnum,  optional] :page            the page number to fetch. defaults to first page
+        # @option params [Fixnum,  optional] :limit           the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=291
+        def get_events( params )
+          LastFM.get( "user.getEvents", params )
+        end
+
+        # Get a list of the user's friends on Last.fm.
+        #
+        # @option params [String,  required] :user            last.fm username
+        # @option params [Boolean, optional] :recenttracks    whether or not to include information about friends' recent listening in the response.
+        # @option params [Fixnum,  optional] :page            the page number to fetch. defaults to first page
+        # @option params [Fixnum,  optional] :limit           the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=263
+        def get_friends( params )
+          LastFM.get( "user.getFriends", params )
+        end
+
+        # Get information about a user profile.
+        #
+        # @option params [String, optional] :user   user to fetch info for. defaults to the authenticated user
+        # @see http://www.last.fm/api/show?service=344
+        def get_info( params )
+          LastFM.get( "user.getInfo", params )
+        end
+
+        # Get a list of tracks loved by a user.
+        #
+        # @option params [String, required] :user     last.fm username
+        # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+        # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=329
+        def get_loved_tracks( params )
+          LastFM.get( "user.getLovedTracks", params )
+        end
+
+        # Get a list of a user's neighbours on Last.fm.
+        #
+        # @option params [String, required] :user     last.fm username
+        # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=264
+        def get_neighbors( params )
+          LastFM.get( "user.getNeighbonrs", params )
+        end
+
+        # Gets a list of upcoming releases based on a user's musical taste.
+        #
+        # @option params [String,  required] :user      last.fm username
+        # @option params [Boolean, optional] :userecs   if true, return new releases based on artist recommendations. otherwise, it is based on their library (the default)
+        # @see http://www.last.fm/api/show?service=444
+        def get_new_releases( params )
+          LastFM.get( "user.getNewReleases", params )
+        end
+
+        # Get a list of all events a user has attended in the past.
+        #
+        # @option params [String, required] :user     last.fm username
+        # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+        # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=343
+        def get_past_events( params )
+          LastFM.get( "user.getPastEvents", params )
+        end
+
+        # Get the user's personal tags.
+        #
+        # @option params [String, required] :user           last.fm username
+        # @option params [String, required] :tag            the tag you're interested in
+        # @option params [String, required] :taggingtype    the type of items which have been tagged. accepted types are 'artist', 'album', or 'track'
+        # @option params [Fixnum, optional] :page           the page number to fetch. defaults to first page
+        # @option params [Fixnum, optional] :limit          the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=455
+        def get_personal_tags( params )
+          LastFM.get( "user.getPersonalTags", params )
+        end
+
+        # Get a list of a user's playlists.
+        #
+        # @option params [String, required] :user   last.fm username
+        # @see http://www.last.fm/api/show?service=313
+        def get_playlists( params )
+          LastFM.get( "user.getPlaylists", params )
+        end
+
+        # Get a list of the recent Stations listened to by a user.
+        #
+        # @option params [String, required] :user     last.fm username
+        # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+        # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=414
+        def get_recent_stations( params )
+          LastFM.requires_authentication
+          LastFM.get( "user.getRecentStations", params, :secure )
+        end
+
+        # Get a list of the recent tracks listened to by a user. Also includes
+        # the currently playing track with the nowplaying="true" attribute if
+        # the user is currently listening.
+        #
+        # @option params [String, required] :user     last.fm username
+        # @option params [Time,   optional] :from     display scrobbles after this time, formatted as unix UTC integer timestamp
+        # @option params [Time,   optional] :to       display scrobbles before this time, formatted as unix UTC integer timestamp
+        # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+        # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=278
+        def get_recent_tracks( params )
+          LastFM.get( "user.getRecentTracks", params )
+        end
+
+        # Get Last.fm artist recommendations for a user.
+        #
+        # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+        # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=388
+        def get_recommended_artists( params )
+          LastFM.requires_authentication
+          LastFM.get( "user.getRecommendedArtists", params, :secure )
+        end
+
+        # Get a paginated list of all events recommended to a user by Last.fm, based on their listening profile.
+        #
+        # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+        # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=375
+        def get_recommended_events( params )
+          LastFM.requires_authentication
+          LastFM.get( "user.getRecommendedEvents", params, :secure )
+        end
+
+        # Get shouts for a user.
+        #
+        # @option params [String, required] :user     last.fm username
+        # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+        # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=401
+        def get_shouts( params )
+          LastFM.get( "user.getShouts", params, :secure )
+        end
+
+        # Get the top albums listened to by a user, based on an optional time period.
+        #
+        # @option params [String, required] :user     last.fm username
+        # @option params [String, optional] :period   time period over which to retrieve top albums for. accepted values are 'overall', '7day', '3month', '6month' or '12month'
+        # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+        # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=299
+        def get_top_albums( params )
+          LastFM.get( "user.getTopAlbums", params )
+        end
+
+        # Get the top artists listened to by a user, based on an optional time period.
+        #
+        # @option params [String, required] :user     last.fm username
+        # @option params [String, optional] :period   time period over which to retrieve top artists for. accepted values are 'overall', '7day', '3month', '6month' or '12month'
+        # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+        # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=300
+        def get_top_artists( params )
+          LastFM.get( "user.getTopArtists", params )
+        end
+
+        # Get the top tags used by a user.
+        #
+        # @option params [String, required] :user     last.fm username
+        # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=123
+        def get_top_tags( params )
+          LastFM.get( "user.getTopTags", params )
+        end
+
+        # Get the top tracks listened to by a user, based on an optional time period.
+        #
+        # @option params [String, required] :user     last.fm username
+        # @option params [String, optional] :period   time period over which to retrieve top tracks for. accepted values are 'overall', '7day', '3month', '6month' or '12month'
+        # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+        # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=301
+        def get_top_tracks( params )
+          LastFM.get( "user.getTopTracks", params )
+        end
+
+        # Get an album chart for a user, for a given date range. Defaults to the most recent chart.
+        #
+        # @option params [String, required] :user     last.fm username
+        # @option params [String, optional] :from     date at which the chart should start. (see: User.get_weekly_chart_list)
+        # @option params [String, optional] :to       date at which the chart should end. (see: User.get_weekly_chart_list)
+        # @see http://www.last.fm/api/show?service=279
+        def get_weekly_album_chart( params )
+          LastFM.get( "user.getWeeklyAlbumChart", params )
+        end
+
+        # Get an artist chart for a user, for a given date range. Defaults to the most recent chart.
+        #
+        # @option params [String, required] :user     last.fm username
+        # @option params [String, optional] :from     date at which the chart should start. (see: User.get_weekly_chart_list)
+        # @option params [String, optional] :to       date at which the chart should end. (see: User.get_weekly_chart_list)
+        # @see http://www.last.fm/api/show?service=281
+        def get_weekly_artist_chart( params )
+          LastFM.get( "user.getWeeklyArtistChart", params )
+        end
+
+        # Get a list of available charts for this user, expressed as date ranges which can be sent to the chart services.
+        #
+        # @option params [String, required] :user   last.fm username
+        # @see http://www.last.fm/api/show?service=280
+        def get_weekly_chart_list( params )
+          LastFM.get( "user.getWeeklyChartList", params )
+        end
+
+        # Get a track chart for a user, for a given date range. Defaults to the most recent chart.
+        #
+        # @option params [String, required] :user     last.fm username
+        # @option params [String, optional] :from     date at which the chart should start. (see: User.get_weekly_chart_list)
+        # @option params [String, optional] :to       date at which the chart should end. (see: User.get_weekly_chart_list)
+        # @see http://www.last.fm/api/show?service=282
+        def get_weekly_track_chart( params )
+          LastFM.get( "user.getWeeklyTrackChart", params )
+        end
+
+        # Shout on a user's shoutbox.
+        #
+        # @option params [String, required] :user       user to shout on
+        # @option params [String, required] :message    message to post to the shoutbox
+        # @see http://www.last.fm/api/show?service=411
+        def shout( params )
+          LastFM.requires_authentication
+          LastFM.post( "user.shout", params )
+        end
+
+      end
+    end
+  end 
+end

data/lib/lastfm/api/venue.rb

@@ -0,0 +1,40 @@
+module LastFM
+  module Api
+    class Venue
+      class << self
+
+        # Get a list of upcoming events for a venue.
+        #
+        # @option params [Fixnum,  required] :venue           the id for the venue to fetch event listings for
+        # @option params [Boolean, optional] :festivalsonly   whether only festivals should be returned, or all events
+        # @see http://www.last.fm/api/show?service=394
+        def get_events( params )
+          LastFM.get( "venue.getEvents", params )
+        end
+
+        # Get a paginated list of all the events held at this venue in the past.
+        #
+        # @option params [Fixnum,  required] :venue           the id for the venue to fetch event listings for
+        # @option params [Boolean, optional] :festivalsonly   whether only festivals should be returned, or all events
+        # @option params [Fixnum,  optional] :page            the page number to fetch. defaults to first page
+        # @option params [Fixnum,  optional] :limit           the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=395
+        def get_past_events( params )
+          LastFM.get( "venue.getPastEvents", params )
+        end
+
+        # Search for a venue by venue name.
+        #
+        # @option params [String, required] :venue      the venue name to search for
+        # @option params [String, optional] :country    a country name used to limit results, as defined by ISO 3166-1
+        # @option params [Fixnum, optional] :page       the page number to fetch. defaults to first page
+        # @option params [Fixnum, optional] :limit      the number of results to fetch per page. defaults to 50
+        # @see http://www.last.fm/api/show?service=396
+        def search( params )
+          LastFM.get( "venue.search", params )
+        end
+
+      end
+    end
+  end 
+end