rscrobbler 0.2.2 → 0.3.0

data/lib/lastfm/track.rb

@@ -1,57 +1,324 @@
-module LastFM
-
-  # @attr [LastFM::Album] album
-  # @attr [LastFM::Artist, String] artist
-  # @attr [Fixnum] duration
-  # @attr [Fixnum] id
-  # @attr [Hash] images
-  # @attr [Fixnum] listeners
-  # @attr [String] mbid
-  # @attr [String] name
-  # @attr [Fixnum] playcount
-  # @attr [Fixnum] position
-  # @attr [Boolean] streamable
-  # @attr [Boolean] streamable_fulltrack
-  # @attr [Array] tags
-  # @attr [String] url
-  # @attr [LastFM::Wii] wiki
-  class Track < Struct.new(:album, :artist, :duration, :id, :images, :listeners, :mbid, :name, :playcount, :position, :streamable, :streamable_fulltrack, :tags, :url, :wiki)
-
-    def update_from_node(node)
-      case node.name.to_sym
-        when :name
-          self.name = node.content
-        when :id
-          self.id = node.content.to_i
-        when :duration
-          self.duration = node.content.to_i
-        when :mbid
-          self.mbid = node.content
-        when :url
-          self.url = node.content
-        when :listeners
-          self.listeners = node.content.to_i
-        when :playcount
-          self.playcount = node.content.to_i
-        when :streamable
-          self.streamable = (node.content == '1')
-          self.streamable_fulltrack = (node['fulltrack'] == '1')
-        when :image
-          self.images ||= {}
-          self.images.merge!({node['size'].to_sym => node.content})
-        when :artist
-          self.artist = (node.find('*').count == 0) ? node.content : LastFM::Artist.from_xml(node)
-        when :album
-          self.position = node['position'].to_i
-          self.album = LastFM::Album.from_xml(node)
-        when :toptags
-          self.tags = node.find('tag').map do |tag|
-            LastFM::Tag.from_xml(tag)
-          end
-        when :wiki
-          self.wiki = LastFM::Wiki.from_xml(node)
-      end
-    end
-
-  end
-end
+module LastFM
+
+  # @attr [LastFM::Album] album
+  # @attr [LastFM::Artist, String] artist
+  # @attr [Fixnum] duration
+  # @attr [Fixnum] id
+  # @attr [Hash] images
+  # @attr [Fixnum] listeners
+  # @attr [String] mbid
+  # @attr [String] name
+  # @attr [Fixnum] playcount
+  # @attr [Fixnum] position
+  # @attr [Boolean] streamable
+  # @attr [Boolean] streamable_fulltrack
+  # @attr [Array] tags
+  # @attr [String] url
+  # @attr [LastFM::Wii] wiki
+  class Track < Struct.new(:album, :artist, :duration, :id, :images, :listeners, :mbid, :name, :playcount, :position, :streamable, :streamable_fulltrack, :tags, :url, :wiki)
+
+    def update_from_node(node)
+      case node.name.to_sym
+        when :name
+          self.name = node.content
+        when :id
+          self.id = node.content.to_i
+        when :duration
+          self.duration = node.content.to_i
+        when :mbid
+          self.mbid = node.content
+        when :url
+          self.url = node.content
+        when :listeners
+          self.listeners = node.content.to_i
+        when :playcount
+          self.playcount = node.content.to_i
+        when :streamable
+          self.streamable = (node.content == '1')
+          self.streamable_fulltrack = (node['fulltrack'] == '1')
+        when :image
+          self.images ||= {}
+          self.images.merge!({node['size'].to_sym => node.content})
+        when :artist
+          self.artist = (node.find('*').count == 0) ? node.content : LastFM::Artist.from_xml(node)
+        when :album
+          self.position = node['position'].to_i
+          self.album = LastFM::Album.from_xml(node)
+        when :toptags
+          self.tags = node.find('tag').map do |tag|
+            LastFM::Tag.from_xml(tag)
+          end
+        when :wiki
+          self.wiki = LastFM::Wiki.from_xml(node)
+      end
+    end
+
+    # API Methods
+    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

data/lib/lastfm/user.rb

@@ -0,0 +1,264 @@
+module LastFM
+  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