rscrobbler 0.0.6 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/lib/lastfm/track.rb CHANGED
@@ -4,124 +4,243 @@ module LastFM
4
4
 
5
5
  TYPE = 'track'
6
6
 
7
+ # Add a list of user supplied tags to a track.
8
+ #
9
+ # @option params [String, required] :artist the artist name
10
+ # @option params [String, required] :track the track name
11
+ # @option params [Array, required] :tags array of tags to apply to this track. accepts a maximum of 10.
7
12
  # @see http://www.last.fm/api/show?service=304
8
- def add_tags( track, artist, tags )
13
+ def add_tags( params )
9
14
  LastFM.requires_authentication
10
- LastFM.post( "#{TYPE}.addTags", 'track'=>track, 'artist'=>artist, 'tags'=>tags )
15
+ LastFM.post( "#{TYPE}.addTags", params )
11
16
  end
12
17
 
18
+ # Ban a track for the current user.
19
+ #
20
+ # @option params [String, required] :artist the artist name
21
+ # @option params [String, required] :track the track name
13
22
  # @see http://www.last.fm/api/show?service=261
14
- def ban( track, artist )
23
+ def ban( params )
15
24
  LastFM.requires_authentication
16
- LastFM.post( "#{TYPE}.ban", 'track'=>track, 'artist'=>artist )
25
+ LastFM.post( "#{TYPE}.ban", params )
17
26
  end
18
27
 
28
+ # Get a list of buy Links for a track.
29
+ #
30
+ # @option params [String, required unless :mbid] :artist the artist name
31
+ # @option params [String, required unless :mbid] :track the track name
32
+ # @option params [String, optional] :mbid the musicbrainz id for the track
33
+ # @option params [Boolean, optional] :autocorrect correct misspelled artist and track names to be returned in the response
34
+ # @option params [String, optional] :country a country name, as defined by ISO 3166-1
19
35
  # @see http://www.last.fm/api/show?service=431
20
- def get_buylinks( track = nil, artist = nil, mbid = nil, autocorrect = nil, country = nil )
21
- raise ArgumentError unless artist && track || mbid
22
- LastFM.get( "#{TYPE}.getBuylinks", !:secure, 'track'=>track, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'country'=>country )
36
+ def get_buylinks( params )
37
+ LastFM.get( "#{TYPE}.getBuylinks", params )
23
38
  end
24
39
 
40
+ # Use the last.fm corrections data to check whether the supplied track has a correction to a canonical track
41
+ #
42
+ # @option params [String, required] :artist the artist name to correct
43
+ # @option params [String, required] :track the track name to correct
25
44
  # @see http://www.last.fm/api/show?service=447
26
- def get_correction( track, artist )
27
- LastFM.get( "#{TYPE}.getCorrection", !:secure, 'track'=>track, 'artist'=>artist )
45
+ def get_correction( params )
46
+ LastFM.get( "#{TYPE}.getCorrection", params )
28
47
  end
29
48
 
49
+ # Retrieve track metadata associated with a fingerprint id generated by the Last.fm Fingerprinter.
50
+ # Returns track elements, along with a 'rank' value between 0 and 1 reflecting the confidence for
51
+ # each match.
52
+ #
53
+ # @option params [String, required] :fingerprint_id the fingerprint id to look up
30
54
  # @see http://www.last.fm/api/show?service=441
31
- def get_fingerprint_metadata( fingerprint_id )
32
- LastFM.get( "#{TYPE}.getFingerPrintMetadata", !:secure, 'fingerprintid'=>fingerprint_id )
33
- end
34
-
55
+ # @see https://github.com/lastfm/Fingerprinter
56
+ # @see http://blog.last.fm/2010/07/09/fingerprint-api-and-app-updated
57
+ def get_fingerprint_metadata( params )
58
+ LastFM.get( "#{TYPE}.getFingerPrintMetadata", params )
59
+ end
60
+
61
+ # Get the metadata for a track.
62
+ #
63
+ # @option params [String, required unless :mbid] :artist the artist name
64
+ # @option params [String, required unless :mbid] :track the track name
65
+ # @option params [String, optional] :mbid the musicbrainz id for the track
66
+ # @option params [Boolean, optional] :autocorrect correct misspelled artist and track names to be returned in the response
67
+ # @option params [String, optional] :username username whose playcount for, and whether they've loved, this track is to be returned in the reponse
35
68
  # @see http://www.last.fm/api/show?service=356
36
- def get_info( track = nil, artist = nil, mbid = nil, autocorrect = nil, username = nil )
37
- raise ArgumentError unless artist && track || mbid
38
- LastFM.get( "#{TYPE}.getInfo", !:secure, 'track'=>track, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'username'=>username )
39
- end
40
-
69
+ def get_info( params )
70
+ LastFM.get( "#{TYPE}.getInfo", params )
71
+ end
72
+
73
+ # Get shouts for a track.
74
+ #
75
+ # @option params [String, required unless :mbid] :artist the artist name
76
+ # @option params [String, required unless :mbid] :track the track name
77
+ # @option params [String, optional] :mbid the musicbrainz id for the track
78
+ # @option params [Boolean, optional] :autocorrect correct misspelled artist and track names to be returned in the response
79
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
80
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
41
81
  # @see http://www.last.fm/api/show?service=453
42
- def get_shouts( track = nil, artist = nil, mbid = nil, autocorrect = nil, limit = nil, page = nil )
43
- raise ArgumentError unless artist && track || mbid
44
- LastFM.get( "#{TYPE}.getShouts", !:secure, 'track'=>track, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'limit'=>limit, 'page'=>page )
82
+ def get_shouts( params )
83
+ LastFM.get( "#{TYPE}.getShouts", params )
45
84
  end
46
85
 
86
+ # Get similar tracks for a track on Last.fm, based on listening data.
87
+ #
88
+ # @option params [String, required unless :mbid] :artist the artist name
89
+ # @option params [String, required unless :mbid] :track the track name
90
+ # @option params [String, optional] :mbid the musicbrainz id for the track
91
+ # @option params [Boolean, optional] :autocorrect correct misspelled artist and track names to be returned in the response
92
+ # @option params [Fixnum, optional] :limit the number of results to fetch. defaults to 50
47
93
  # @see http://www.last.fm/api/show?service=319
48
- def get_similar( track = nil, artist = nil, mbid = nil, autocorrect = nil, limit = nil )
49
- raise ArgumentError unless artist && track || mbid
50
- LastFM.get( "#{TYPE}.getSimilar", !:secure, 'track'=>track, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'limit'=>limit )
94
+ def get_similar( params )
95
+ LastFM.get( "#{TYPE}.getSimilar", params )
51
96
  end
52
97
 
98
+ # Get the tags on a track.
99
+ #
100
+ # @option params [String, required unless :mbid] :artist the artist name
101
+ # @option params [String, required unless :mbid] :track the track name
102
+ # @option params [String, optional] :mbid the musicbrainz id for the track
103
+ # @option params [Boolean, optional] :autocorrect correct misspelled artist and track names to be returned in the response
104
+ # @option params [String, optional] :user if called in non-authenticated mode you must specify the user to look up
53
105
  # @see http://www.last.fm/api/show?service=320
54
- def get_tags( track = nil, artist = nil, mbid = nil, autocorrect = nil )
55
- raise ArgumentError unless artist && track || mbid
56
- LastFM.requires_authentication
57
- LastFM.post( "#{TYPE}.getTags", 'track'=>track, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect )
58
- end
59
-
106
+ def get_tags( params )
107
+ secure = !params.include?(:user)
108
+ LastFM.requires_authentication if secure
109
+ LastFM.post( "#{TYPE}.getTags", params, secure )
110
+ end
111
+
112
+ # Get the top fans for a track, based on listening data.
113
+ #
114
+ # @option params [String, required unless :mbid] :artist the artist name
115
+ # @option params [String, required unless :mbid] :track the track name
116
+ # @option params [String, optional] :mbid the musicbrainz id for the track
117
+ # @option params [Boolean, optional] :autocorrect correct misspelled artist and track names to be returned in the response
60
118
  # @see http://www.last.fm/api/show?service=312
61
- def get_top_fans( track = nil, artist = nil, mbid = nil, autocorrect = nil )
62
- raise ArgumentError unless artist && track || mbid
63
- LastFM.get( "#{TYPE}.getTopFans", !:secure, 'track'=>track, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect )
119
+ def get_top_fans( params )
120
+ LastFM.get( "#{TYPE}.getTopFans", params )
64
121
  end
65
122
 
123
+ # Get the top fans for a track, ordered by tag count.
124
+ #
125
+ # @option params [String, required unless :mbid] :artist the artist name
126
+ # @option params [String, required unless :mbid] :track the track name
127
+ # @option params [String, optional] :mbid the musicbrainz id for the track
128
+ # @option params [Boolean, optional] :autocorrect correct misspelled artist and track names to be returned in the response
66
129
  # @see http://www.last.fm/api/show?service=289
67
- def get_top_tags( track = nil, artist = nil, mbid = nil, autocorrect = nil )
68
- raise ArgumentError unless artist && track || mbid
69
- LastFM.get( "#{TYPE}.getTopTags", !:secure, 'track'=>track, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect )
130
+ def get_top_tags( params )
131
+ LastFM.get( "#{TYPE}.getTopTags", params )
70
132
  end
71
133
 
134
+ # Love a track for the current user.
135
+ #
136
+ # @option params [String, required] :artist the artist name
137
+ # @option params [String, required] :track the track name
72
138
  # @see http://www.last.fm/api/show?service=260
73
- def love( track, artist )
139
+ def love( params )
74
140
  LastFM.requires_authentication
75
- LastFM.post( "#{TYPE}.love", 'track'=>track, 'artist'=>artist )
141
+ LastFM.post( "#{TYPE}.love", params )
76
142
  end
77
143
 
144
+ # Remove a user's tag from a track.
145
+ #
146
+ # @option params [String, required] :artist the artist name
147
+ # @option params [String, required] :track the track name
148
+ # @option params [String, required] :tag a single user tag to remove from this track
78
149
  # @see http://www.last.fm/api/show?service=316
79
- def remove_tag( track, artist, tag )
150
+ def remove_tag( params )
80
151
  LastFM.requires_authentication
81
- LastFM.post( "#{TYPE}.removeTag", 'track'=>track, 'artist'=>artist, 'tag'=>tag )
82
- end
83
-
152
+ LastFM.post( "#{TYPE}.removeTag", params )
153
+ end
154
+
155
+ # Used to add a track-play to a user's profile. Scrobble a track, or a batch of tracks.
156
+ # Single tracks may be passed using the Object types listed, batches of tracks must be
157
+ # passed in as Arrays of each Object type. Allows up to a maximum of 50 scrobbles per
158
+ # batch. For batch scrobbles, Array indices of optional parameters must line up with
159
+ # the indicies of their corresponding tracks.
160
+ #
161
+ # @option params [String, required unless :mbid] :artist artist name
162
+ # @option params [String, required unless :mbid] :track track name
163
+ # @option params [String, optional] :mbid the musicbrainz id for the track
164
+ # @option params [Time, optional] :timestamp time the track started playing
165
+ # @option params [String, optional] :album album name
166
+ # @option params [String, optional] :album_artist album artist, if this differend from the track artist
167
+ # @option params [Fixnum, optional] :track_number track number of the track on the album
168
+ # @option params [Fixnum, optional] :duration track length, in seconds
169
+ # @option params [String, optional] :stream_id track stream id, received from the radio.getPlaylist service
170
+ # @option params [Boolean, optional] :chosen_by_user whether or not the user chose the track
171
+ # @option params [String, optional] :context sub-client version (not public, only enabled for certain api keys)
84
172
  # @see http://www.last.fm/api/show?service=443
85
- def scrobble( tracks, artists, timestamps, albums = nil, album_artists = nil, contexts = nil, stream_ids = nil, track_numbers = nil, mbids = nil, durations = nil, chosen_by_users = nil )
173
+ def scrobble( params )
86
174
  LastFM.requires_authentication
87
- params = {}
88
- %w[tracks artists timestamps albums album_artists contexts stream_ids track_numbers mbids durations chosen_by_users].each{|var|
89
- camel_var = var.chomp('s').split('_').map{|a| a.capitalize}.join
90
- camel_var = camel_var[0, 1].downcase + camel_var[1..-1]
91
- Array(eval(var)).each_with_index{|val, i|
92
- params["#{camel_var}[#{i}]"] = val
93
- }
94
- }
95
- LastFM.post( "#{TYPE}.scrobble", params )
96
- end
97
-
175
+ # Tracks are passed to the service using array notation for each of the above params
176
+ array_params = {}
177
+ params.each do |hkey, hval|
178
+ hval = hval.to_i if hval.is_a?(Time)
179
+ Array(hval).each_with_index do |aval, index|
180
+ array_params["#{hkey}[#{index}]"] = aval
181
+ end
182
+ end
183
+ LastFM.post( "#{TYPE}.scrobble", array_params )
184
+ end
185
+
186
+ # Search for a track by track name. Returns track matches sorted by relevance.
187
+ #
188
+ # @option params [String, required] :track the track name
189
+ # @option params [String, optional] :artist narrow results based on an artist
190
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
191
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
98
192
  # @see http://www.last.fm/api/show?service=286
99
- def search( track, artist = nil, limit = nil, page = nil )
100
- LastFM.get( "#{TYPE}.search", !:secure, 'track'=>track, 'artist'=>artist, 'limit'=>limit, 'page'=>page )
193
+ def search( params )
194
+ LastFM.get( "#{TYPE}.search", params )
101
195
  end
102
196
 
197
+ # Share a track twith one or more Last.fm users or other friends.
198
+ #
199
+ # @option params [String, required] :artist the artist name
200
+ # @option params [String, required] :track the track name
201
+ # @option params [Array, required] :recipient a list of email addresses or Last.fm usernames. maximum is 10
202
+ # @option params [String, optional] :message an optional message to send. if not supplied a default message will be used
203
+ # @option params [Boolean, optional] :public optionally show in the sharing users activity feed. defaults to false
103
204
  # @see http://www.last.fm/api/show?service=305
104
- def share( track, artist, recipient, message = nil, public = nil )
205
+ def share( params )
105
206
  LastFM.requires_authentication
106
- LastFM.post( "#{TYPE}.share", 'track'=>track, 'artist'=>artist, 'recipient'=>recipient, 'message'=>message, 'public'=>public )
207
+ LastFM.post( "#{TYPE}.share", params )
107
208
  end
108
209
 
210
+ # Unban a track for the current user.
211
+ #
212
+ # @option params [String, required] :artist the artist name
213
+ # @option params [String, required] :track the track name
109
214
  # @see http://www.last.fm/api/show?service=449
110
- def unban( track, artist )
215
+ def unban( params )
111
216
  LastFM.requires_authentication
112
- LastFM.post( "#{TYPE}.unban", 'track'=>track, 'artist'=>artist )
217
+ LastFM.post( "#{TYPE}.unban", params )
113
218
  end
114
219
 
220
+ # Unlove a track for the current user.
221
+ #
222
+ # @option params [String, required] :artist the artist name
223
+ # @option params [String, required] :track the track name
115
224
  # @see http://www.last.fm/api/show?service=440
116
- def unlove( track, artist )
225
+ def unlove( params )
117
226
  LastFM.requires_authentication
118
- LastFM.post( "#{TYPE}.unlove", 'track'=>track, 'artist'=>artist )
119
- end
120
-
227
+ LastFM.post( "#{TYPE}.unlove", params )
228
+ end
229
+
230
+ # Used to notify Last.fm that a user has started listening to a track.
231
+ #
232
+ # @option params [String, required unless :mbid] :artist artist name
233
+ # @option params [String, required unless :mbid] :track track name
234
+ # @option params [String, optional] :mbid the musicbrainz id for the track
235
+ # @option params [String, optional] :album album name
236
+ # @option params [String, optional] :album_artist album artist, if this differend from the track artist
237
+ # @option params [Fixnum, optional] :track_number track number of the track on the album
238
+ # @option params [Fixnum, optional] :duration track length, in seconds
239
+ # @option params [String, optional] :context sub-client version (not public, only enabled for certain api keys)
121
240
  # @see http://www.last.fm/api/show?service=454
122
- def update_now_playing( track, artist, album = nil, album_artist = nil, context = nil, track_number = nil, mbid = nil, duration = nil )
241
+ def update_now_playing( params )
123
242
  LastFM.requires_authentication
124
- LastFM.post( "#{TYPE}.updateNowPlaying", 'track'=>track, 'artist'=>artist, 'album'=>album, 'albumArtist'=>album_artist, 'context'=>context, 'trackNumber'=>track_number, 'mbid'=>mbid, 'duration'=>duration )
243
+ LastFM.post( "#{TYPE}.updateNowPlaying", params )
125
244
  end
126
245
 
127
246
  end
data/lib/lastfm/user.rb CHANGED
@@ -4,136 +4,261 @@ module LastFM
4
4
 
5
5
  TYPE = 'user'
6
6
 
7
+ # Get a list of tracks by a given artist scrobbled by this user,
8
+ # including scrobble time. Can be limited to specific timeranges,
9
+ # defaults to all time.
10
+ #
11
+ # @option params [String, required] :user last.fm username to fetch the recent tracks for
12
+ # @option params [String, required] :artist the artist name to fetch tracks for
13
+ # @option params [Time, optional] :startTimestamp a unix timestamp to start at
14
+ # @option params [Time, optional] :endTimestamp a unix timestamp to end at
15
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
7
16
  # @see http://www.last.fm/api/show?service=432
8
- def get_artist_tracks( user, artist, start_timestamp = nil, end_timestamp = nil, page = nil )
9
- LastFM.get( "#{TYPE}.getArtistTracks", !:secure, 'user'=>user, 'artist'=>artist, 'startTimestamp'=>start_timestamp, 'endTimestamp'=>end_timestamp, 'page'=>page )
17
+ def get_artist_tracks( params )
18
+ LastFM.get( "#{TYPE}.getArtistTracks", params )
10
19
  end
11
20
 
21
+ # Get a list of tracks banned by a user.
22
+ #
23
+ # @option params [String, required] :user last.fm username
24
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
25
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
12
26
  # @see http://www.last.fm/api/show?service=448
13
- def get_banned_tracks( user, limit = nil, page = nil )
14
- LastFM.get( "#{TYPE}.getBannedTracks", !:secure, 'user'=>user, 'limit'=>limit, 'page'=>page )
27
+ def get_banned_tracks( params )
28
+ LastFM.get( "#{TYPE}.getBannedTracks", params )
15
29
  end
16
30
 
31
+ # Get a list of upcoming events that this user is attending.
32
+ #
33
+ # @option params [String, required] :user last.fm username
34
+ # @option params [Boolean, optional] :festivalsonly whether only festivals should be returned, or all events
35
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
36
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
17
37
  # @see http://www.last.fm/api/show?service=291
18
- def get_events( user, limit = nil, page = nil )
19
- LastFM.get( "#{TYPE}.getEvents", !:secure, 'user'=>user, 'limit'=>limit, 'page'=>page )
38
+ def get_events( params )
39
+ LastFM.get( "#{TYPE}.getEvents", params )
20
40
  end
21
41
 
42
+ # Get a list of the user's friends on Last.fm.
43
+ #
44
+ # @option params [String, required] :user last.fm username
45
+ # @option params [Boolean, optional] :recenttracks whether or not to include information about friends' recent listening in the response.
46
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
47
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
22
48
  # @see http://www.last.fm/api/show?service=263
23
- def get_friends( user, recent_tracks = nil, limit = nil, page = nil )
24
- LastFM.get( "#{TYPE}.getFriends", !:secure, 'user'=>user, 'recenttracks'=>recent_tracks, 'limit'=>limit, 'page'=>page )
49
+ def get_friends( params )
50
+ LastFM.get( "#{TYPE}.getFriends", params )
25
51
  end
26
52
 
53
+ # Get information about a user profile.
54
+ #
55
+ # @option params [String, optional] :user user to fetch info for. defaults to the authenticated user
27
56
  # @see http://www.last.fm/api/show?service=344
28
- def get_info( user = nil )
29
- LastFM.get( "#{TYPE}.getInfo", !:secure, 'user'=>user )
57
+ def get_info( params )
58
+ LastFM.get( "#{TYPE}.getInfo", params )
30
59
  end
31
60
 
61
+ # Get a list of tracks loved by a user.
62
+ #
63
+ # @option params [String, required] :user last.fm username
64
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
65
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
32
66
  # @see http://www.last.fm/api/show?service=329
33
- def get_loved_tracks( user, limit = nil, page = nil )
34
- LastFM.get( "#{TYPE}.getLovedTracks", !:secure, 'user'=>user, 'limit'=>limit, 'page'=>page )
67
+ def get_loved_tracks( params )
68
+ LastFM.get( "#{TYPE}.getLovedTracks", params )
35
69
  end
36
70
 
71
+ # Get a list of a user's neighbours on Last.fm.
72
+ #
73
+ # @option params [String, required] :user last.fm username
74
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
37
75
  # @see http://www.last.fm/api/show?service=264
38
- def get_neighbors( user, limit = nil )
39
- LastFM.get( "#{TYPE}.getNeighbonrs", !:secure, 'user'=>user, 'limit'=>limit )
76
+ def get_neighbors( params )
77
+ LastFM.get( "#{TYPE}.getNeighbonrs", params )
40
78
  end
41
79
 
80
+ # Gets a list of upcoming releases based on a user's musical taste.
81
+ #
82
+ # @option params [String, required] :user last.fm username
83
+ # @option params [Boolean, optional] :userecs if true, return new releases based on artist recommendations. otherwise, it is based on their library (the default)
42
84
  # @see http://www.last.fm/api/show?service=444
43
- def get_new_releases( user, useresc = nil )
44
- LastFM.get( "#{TYPE}.getNewReleases", !:secure, 'user'=>user, 'useresc'=>useresc )
85
+ def get_new_releases( params )
86
+ LastFM.get( "#{TYPE}.getNewReleases", params )
45
87
  end
46
88
 
89
+ # Get a list of all events a user has attended in the past.
90
+ #
91
+ # @option params [String, required] :user last.fm username
92
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
93
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
47
94
  # @see http://www.last.fm/api/show?service=343
48
- def get_past_events( user, limit = nil, page = nil )
49
- LastFM.get( "#{TYPE}.getPastEvents", !:secure, 'user'=>user, 'limit'=>limit, 'page'=>page )
95
+ def get_past_events( params )
96
+ LastFM.get( "#{TYPE}.getPastEvents", params )
50
97
  end
51
98
 
52
- @tagging_types = [ 'artist', 'album', 'track' ]
53
-
99
+ # Get the user's personal tags.
100
+ #
101
+ # @option params [String, required] :user last.fm username
102
+ # @option params [String, required] :tag the tag you're interested in
103
+ # @option params [String, required] :taggingtype the type of items which have been tagged. accepted types are 'artist', 'album', or 'track'
104
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
105
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
54
106
  # @see http://www.last.fm/api/show?service=455
55
- def get_personal_tags( user, tag, tagging_type, limit = nil, page = nil )
56
- raise ArgumentError unless @tagging_types.include?(tagging_type)
57
- LastFM.get( "#{TYPE}.getPersonalTags", !:secure, 'user'=>user, 'tag'=>tag, 'limit'=>limit, 'page'=>page )
107
+ def get_personal_tags( params )
108
+ LastFM.get( "#{TYPE}.getPersonalTags", params )
58
109
  end
59
110
 
111
+ # Get a list of a user's playlists.
112
+ #
113
+ # @option params [String, required] :user last.fm username
60
114
  # @see http://www.last.fm/api/show?service=313
61
- def get_playlists( user )
62
- LastFM.get( "#{TYPE}.getPlaylists", !:secure, 'user'=>user )
115
+ def get_playlists( params )
116
+ LastFM.get( "#{TYPE}.getPlaylists", params )
63
117
  end
64
118
 
119
+ # Get a list of the recent Stations listened to by a user.
120
+ #
121
+ # @option params [String, required] :user last.fm username
122
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
123
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
65
124
  # @see http://www.last.fm/api/show?service=414
66
- def get_recent_stations( user, limit = nil, page = nil )
125
+ def get_recent_stations( params )
67
126
  LastFM.requires_authentication
68
- LastFM.get( "#{TYPE}.getRecentStations", :secure, 'user'=>user, 'limit'=>limit, 'page'=>page )
127
+ LastFM.get( "#{TYPE}.getRecentStations", params, :secure )
69
128
  end
70
129
 
130
+ # Get a list of the recent tracks listened to by a user. Also includes
131
+ # the currently playing track with the nowplaying="true" attribute if
132
+ # the user is currently listening.
133
+ #
134
+ # @option params [String, required] :user last.fm username
135
+ # @option params [Time, optional] :from display scrobbles after this time, formatted as unix UTC integer timestamp
136
+ # @option params [Time, optional] :to display scrobbles before this time, formatted as unix UTC integer timestamp
137
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
138
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
71
139
  # @see http://www.last.fm/api/show?service=278
72
- def get_recent_tracks( user, time_from = nil, time_to = nil, limit = nil, page = nil )
73
- LastFM.get( "#{TYPE}.getRecentTracks", !:secure, 'user'=>user, 'from'=>time_from, 'to'=>time_to, 'limit'=>limit, 'page'=>page )
140
+ def get_recent_tracks( params )
141
+ LastFM.get( "#{TYPE}.getRecentTracks", params )
74
142
  end
75
143
 
144
+ # Get Last.fm artist recommendations for a user.
145
+ #
146
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
147
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
76
148
  # @see http://www.last.fm/api/show?service=388
77
- def get_recommended_artists( limit = nil, page = nil )
149
+ def get_recommended_artists( params )
78
150
  LastFM.requires_authentication
79
- LastFM.get( "#{TYPE}.getRecommendedArtists", :secure, 'limit'=>limit, 'page'=>page )
151
+ LastFM.get( "#{TYPE}.getRecommendedArtists", params, :secure )
80
152
  end
81
153
 
154
+ # Get a paginated list of all events recommended to a user by Last.fm, based on their listening profile.
155
+ #
156
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
157
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
82
158
  # @see http://www.last.fm/api/show?service=375
83
- def get_recommended_events( limit = nil, page = nil )
159
+ def get_recommended_events( params )
84
160
  LastFM.requires_authentication
85
- LastFM.get( "#{TYPE}.getRecommendedEvents", :secure, 'limit'=>limit, 'page'=>page )
161
+ LastFM.get( "#{TYPE}.getRecommendedEvents", params, :secure )
86
162
  end
87
163
 
164
+ # Get shouts for a user.
165
+ #
166
+ # @option params [String, required] :user last.fm username
167
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
168
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
88
169
  # @see http://www.last.fm/api/show?service=401
89
- def get_shouts( user, limit = nil, page = nil )
90
- LastFM.get( "#{TYPE}.getShouts", !:secure, 'user'=>user, 'limit'=>limit, 'page'=>page )
170
+ def get_shouts( params )
171
+ LastFM.get( "#{TYPE}.getShouts", params, :secure )
91
172
  end
92
173
 
174
+ # Get the top albums listened to by a user, based on an optional time period.
175
+ #
176
+ # @option params [String, required] :user last.fm username
177
+ # @option params [String, optional] :period time period over which to retrieve top albums for. accepted values are 'overall', '7day', '3month', '6month' or '12month'
178
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
179
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
93
180
  # @see http://www.last.fm/api/show?service=299
94
- def get_top_albums( user, period = nil, limit = nil, page = nil )
95
- LastFM.get( "#{TYPE}.getTopAlbums", !:secure, 'user'=>user, 'period'=>period, 'limit'=>limit, 'page'=>page )
181
+ def get_top_albums( params )
182
+ LastFM.get( "#{TYPE}.getTopAlbums", params )
96
183
  end
97
184
 
185
+ # Get the top artists listened to by a user, based on an optional time period.
186
+ #
187
+ # @option params [String, required] :user last.fm username
188
+ # @option params [String, optional] :period time period over which to retrieve top artists for. accepted values are 'overall', '7day', '3month', '6month' or '12month'
189
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
190
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
98
191
  # @see http://www.last.fm/api/show?service=300
99
- def get_top_artists( user, period = nil, limit = nil, page = nil )
100
- LastFM.get( "#{TYPE}.getTopArtists", !:secure, 'user'=>user, 'period'=>period, 'limit'=>limit, 'page'=>page )
192
+ def get_top_artists( params )
193
+ LastFM.get( "#{TYPE}.getTopArtists", params )
101
194
  end
102
195
 
196
+ # Get the top tags used by a user.
197
+ #
198
+ # @option params [String, required] :user last.fm username
199
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
103
200
  # @see http://www.last.fm/api/show?service=123
104
- def get_top_tags( user, limit = nil )
105
- LastFM.get( "#{TYPE}.getTopTags", !:secure, 'user'=>user, 'limit'=>limit )
201
+ def get_top_tags( params )
202
+ LastFM.get( "#{TYPE}.getTopTags", params )
106
203
  end
107
204
 
205
+ # Get the top tracks listened to by a user, based on an optional time period.
206
+ #
207
+ # @option params [String, required] :user last.fm username
208
+ # @option params [String, optional] :period time period over which to retrieve top tracks for. accepted values are 'overall', '7day', '3month', '6month' or '12month'
209
+ # @option params [Fixnum, optional] :page the page number to fetch. defaults to first page
210
+ # @option params [Fixnum, optional] :limit the number of results to fetch per page. defaults to 50
108
211
  # @see http://www.last.fm/api/show?service=301
109
- def get_top_tracks( user, period, limit = nil, page = nil )
110
- LastFM.get( "#{TYPE}.getTopTracks", !:secure, 'user'=>user, 'period'=>period, 'limit'=>limit, 'page'=>page )
212
+ def get_top_tracks( params )
213
+ LastFM.get( "#{TYPE}.getTopTracks", params )
111
214
  end
112
215
 
216
+ # Get an album chart for a user, for a given date range. Defaults to the most recent chart.
217
+ #
218
+ # @option params [String, required] :user last.fm username
219
+ # @option params [String, optional] :from date at which the chart should start. (see: User.get_weekly_chart_list)
220
+ # @option params [String, optional] :to date at which the chart should end. (see: User.get_weekly_chart_list)
113
221
  # @see http://www.last.fm/api/show?service=279
114
- def get_weekly_album_chart( user, time_from = nil, time_to = nil )
115
- LastFM.get( "#{TYPE}.getWeeklyAlbumChart", !:secure, 'user'=>user, 'from'=>time_from, 'to'=>time_to )
222
+ def get_weekly_album_chart( params )
223
+ LastFM.get( "#{TYPE}.getWeeklyAlbumChart", params )
116
224
  end
117
225
 
226
+ # Get an artist chart for a user, for a given date range. Defaults to the most recent chart.
227
+ #
228
+ # @option params [String, required] :user last.fm username
229
+ # @option params [String, optional] :from date at which the chart should start. (see: User.get_weekly_chart_list)
230
+ # @option params [String, optional] :to date at which the chart should end. (see: User.get_weekly_chart_list)
118
231
  # @see http://www.last.fm/api/show?service=281
119
- def get_weekly_artist_chart( user, time_from = nil, time_to = nil )
120
- LastFM.get( "#{TYPE}.getWeeklyArtistChart", !:secure, 'user'=>user, 'from'=>time_from, 'to'=>time_to )
232
+ def get_weekly_artist_chart( params )
233
+ LastFM.get( "#{TYPE}.getWeeklyArtistChart", params )
121
234
  end
122
235
 
236
+ # Get a list of available charts for this user, expressed as date ranges which can be sent to the chart services.
237
+ #
238
+ # @option params [String, required] :user last.fm username
123
239
  # @see http://www.last.fm/api/show?service=280
124
- def get_weekly_chart_list( user )
125
- LastFM.get( "#{TYPE}.getWeeklyChartList", !:secure, 'user'=>user )
240
+ def get_weekly_chart_list( params )
241
+ LastFM.get( "#{TYPE}.getWeeklyChartList", params )
126
242
  end
127
243
 
244
+ # Get a track chart for a user, for a given date range. Defaults to the most recent chart.
245
+ #
246
+ # @option params [String, required] :user last.fm username
247
+ # @option params [String, optional] :from date at which the chart should start. (see: User.get_weekly_chart_list)
248
+ # @option params [String, optional] :to date at which the chart should end. (see: User.get_weekly_chart_list)
128
249
  # @see http://www.last.fm/api/show?service=282
129
- def get_weekly_track_chart( user, time_from = nil, time_to = nil )
130
- LastFM.get( "#{TYPE}.getWeeklyTrackChart", !:secure, 'user'=>user, 'from'=>time_from, 'to'=>time_to )
250
+ def get_weekly_track_chart( params )
251
+ LastFM.get( "#{TYPE}.getWeeklyTrackChart", params )
131
252
  end
132
253
 
254
+ # Shout on a user's shoutbox.
255
+ #
256
+ # @option params [String, required] :user user to shout on
257
+ # @option params [String, required] :message message to post to the shoutbox
133
258
  # @see http://www.last.fm/api/show?service=411
134
- def shout( user, message )
259
+ def shout( params )
135
260
  LastFM.requires_authentication
136
- LastFM.post( "#{TYPE}.shout", 'user'=>user, 'message'=>message )
261
+ LastFM.post( "#{TYPE}.shout", params )
137
262
  end
138
263
 
139
264
  end