473 lines
14 KiB
Markdown
473 lines
14 KiB
Markdown
LastfmAPI
|
|
=========
|
|
|
|
This is a wrapper library for James' [lastfm-node][lastfmnode] module, a
|
|
Last.fm API client for Node.js.
|
|
It aims to provide a simpler API for the Last.fm methods with one single
|
|
callback function instead of an options object with handler methods. It
|
|
also adds a signature to all methods that require signing automatically.
|
|
|
|
Getting Started
|
|
---------------
|
|
|
|
Install with npm
|
|
|
|
```sh
|
|
npm install lastfmapi
|
|
```
|
|
|
|
or add it to the `dependencies` array in your package.json file. This
|
|
module follows the [Semantic Versioning][semver] guidelines so you can
|
|
expect all sub-versions of the same major version to have a compatible
|
|
API.
|
|
|
|
Use `require` to load the module
|
|
|
|
```javascript
|
|
var LastfmAPI = require('lastfmapi');
|
|
```
|
|
|
|
and create a new instance as follows:
|
|
|
|
```javascript
|
|
var lfm = new LastfmAPI({
|
|
'api_key' : 'YOUR_API_KEY',
|
|
'secret' : 'YOUR_API_SECRET'
|
|
});
|
|
```
|
|
|
|
Try it out:
|
|
|
|
```javascript
|
|
lfm.track.getInfo({
|
|
'artist' : 'Poliça',
|
|
'track' : 'Wandering Star'
|
|
}, function (err, track) {
|
|
if (err) { throw err; }
|
|
console.log(track);
|
|
});
|
|
```
|
|
|
|
If you don't already have a Last.fm API account, you can get one
|
|
[here][register].
|
|
|
|
Examples
|
|
--------
|
|
|
|
### Authentication for Web Applications
|
|
|
|
_Check out the authentication example in the examples directory for a working example._
|
|
|
|
In order to make signed method calls or use write methods such das
|
|
scrobbling, you need to authenticate your application. Read more about
|
|
web application authentication [here][webauth].
|
|
|
|
To authenticate a user for a web application, first define a callback
|
|
URL (`cb`) that will handle the authentication token. Then create an
|
|
authentication URL and redirect the user to it.
|
|
|
|
```javascript
|
|
var authUrl = lfm.getAuthenticationUrl({ 'cb' : 'http://example.com/auth' });
|
|
console.log(authUrl); // redirect the user to this URL
|
|
```
|
|
|
|
The URL will look something like
|
|
"http://www.last.fm/api/auth/?api_key=YOUR_API_KEY&cb=http%3A%2F%2Fexample.com%2Fauth"
|
|
|
|
After the user has authorized your application, Last.fm will redirect
|
|
the user to your callback URL. Somethig like
|
|
"http://example.com/auth?token=THE_AUTHENTICATION_TOKEN"
|
|
|
|
Then use the `authenticate` method using the received authentication
|
|
token:
|
|
|
|
```javascript
|
|
lfm.authenticate('THE_AUTHENTICATION_TOKEN', function (err, session) {
|
|
if (err) { throw err; }
|
|
console.log(session); // {"name": "LASTFM_USERNAME", "key": "THE_USER_SESSION_KEY"}
|
|
});
|
|
```
|
|
|
|
The `authenticate` method is a short-hand function that does
|
|
`auth.getSession` and stores the session credentials in the `LastfmAPI`
|
|
object using the `setSessionCredentials` method. You could also do the
|
|
same things manually.
|
|
The method will give you an object containing the user's session
|
|
credentials. It is advised that you save this data to disc for later
|
|
use. Session keys do not expire.
|
|
|
|
To authenticate the user again at a later time, simply set the
|
|
credentials using `setSessionCredentials` and you are set to make
|
|
authenticated method calls:
|
|
|
|
```javascript
|
|
lfm.setSessionCredentials('LASTFM_USERNAME', 'THE_USER_SESSION_KEY');
|
|
```
|
|
|
|
### Authentication for Desktop Applications
|
|
_(Coming soon)_
|
|
|
|
### Authentication for Mobile Applications
|
|
_(Coming soon)_
|
|
|
|
### Scrobbling
|
|
|
|
This example requires authentication and assumes you have your session
|
|
credentials at-the-ready. Look at the
|
|
[authentication](#authentication-for-web-applications) example to see
|
|
how it works.
|
|
|
|
```javascript
|
|
var LastfmAPI = require('lastfmapi');
|
|
|
|
// Create a new instance
|
|
var lfm = new LastfmAPI({
|
|
'api_key' : 'YOUR_API_KEY',
|
|
'secret' : 'YOUR_API_SECRET'
|
|
});
|
|
|
|
var mySessionCreds = {
|
|
'username' : 'myLastFmUsername',
|
|
'key' : 'MY_LASTFM_SESSION_KEY'
|
|
};
|
|
|
|
lfm.setSessionCredentials(mySessionCreds.username, mySessionCreds.key);
|
|
|
|
// Scrobble 'Wandering Star' by 'Poliça', 5 minutes ago
|
|
lfm.track.scrobble({
|
|
'artist' : 'Poliça',
|
|
'track' : 'Wandering Star',
|
|
'timestamp' : Math.floor((new Date()).getTime() / 1000) - 300
|
|
|
|
}, function (err, scrobbles) {
|
|
if (err) { return console.log('We\'re in trouble', err); }
|
|
|
|
console.log('We have just scrobbled:', scrobbles);
|
|
});
|
|
```
|
|
|
|
_(More coming soon)_
|
|
|
|
Documentation
|
|
-------------
|
|
|
|
The rule of thumb is that when a method has only required parameters, or
|
|
one or more required and one optional parameter, they will be
|
|
represented in the API as regular function arguments. If the method
|
|
takes one or more required and multiple optional parameters, the
|
|
function will take a `params` object. If all parameters are optional,
|
|
the `params` object becomes optional.
|
|
|
|
The first argument of the callback is always `err`, which is an Error
|
|
object in case of an error or null if everything went well. The second
|
|
argument is the result.
|
|
|
|
The following documentation assumes that `lfm` is an instance of LastfmAPI.
|
|
|
|
##### `new LastfmAPI(options)`
|
|
|
|
The constructor takes an options object with 2 properties: The `api_key`
|
|
property contains your Last.fm API key and `secret` contains your
|
|
Last.fm API secret
|
|
|
|
##### `lfm.api`
|
|
|
|
Exposes the underlying [lastfm-node][lastfmnode] API client so you can
|
|
go "low-level" if you like
|
|
|
|
##### `lfm.getAuthenticationUrl(params)`
|
|
|
|
Constructs and returns an authentication URL. The params object has 2
|
|
optional properties: `cb` is the callback URL and `token` is an
|
|
authentication token
|
|
|
|
##### `lfm.authenticate(token, callback(err, sessionData))`
|
|
|
|
Fetches a Last.fm session and stores the session credentials in the
|
|
object
|
|
|
|
##### `lfm.setSessionCredentials(username, sessionToken)`
|
|
|
|
Stores session credentials that will be used to make API calls that
|
|
require authentication
|
|
|
|
##### `lfm.sessionCredentials`
|
|
|
|
Exposes the session credentials used to make authenticated API calls.
|
|
The object contains 2 properties: `username` is the Last.fm username and
|
|
`key` is the session key
|
|
|
|
|
|
Jump: [Album](#album) | [Artist](#artist) | [Auth](#auth) | [Chart](#chart) | [Geo](#geo) | [Library](#library) | [Tag](#tag) | [Track](#track) | [User](#user)
|
|
|
|
### Album
|
|
|
|
##### `lfm.album.addTags(artist, album, tags, callback(err))`
|
|
|
|
See [docs](http://www.last.fm/api/show/album.addTags). `tags` can be a string or an array.
|
|
|
|
##### `lfm.album.getInfo(params, callback(err, album))`
|
|
|
|
See [docs](http://www.last.fm/api/show/album.getInfo) for params.
|
|
|
|
##### `lfm.album.getTags(params, callback(err, tags))`
|
|
|
|
See [docs](http://www.last.fm/api/show/album.getTags) for params.
|
|
|
|
##### `lfm.album.getTopTags(params, callback(err, toptags))`
|
|
|
|
See [docs](http://www.last.fm/api/show/album.getTopTags) for params.
|
|
|
|
##### `lfm.album.removeTag(artist, album, tag, callback(err))`
|
|
|
|
See [docs](http://www.last.fm/api/show/album.removeTag).
|
|
|
|
##### `lfm.album.search(params, callback(err, results))`
|
|
|
|
See [docs](http://www.last.fm/api/show/album.search) for params.
|
|
|
|
### Artist
|
|
|
|
##### `lfm.artist.addTags(artist, tags, callback(err))`
|
|
|
|
See [docs](http://www.last.fm/api/show/artist.addTags). `tags` can be a string or an array.
|
|
|
|
##### `lfm.artist.getCorrection(artist, callback(err, corrections))`
|
|
|
|
See [docs](http://www.last.fm/api/show/artist.getCorrection).
|
|
|
|
##### `lfm.artist.getInfo(params, callback(err, artist))`
|
|
|
|
See [docs](http://www.last.fm/api/show/artist.getInfo) for params.
|
|
|
|
##### `lfm.artist.getSimilar(params, callback(err, similarArtists))`
|
|
|
|
See [docs](http://www.last.fm/api/show/artist.getSimilar) for params.
|
|
|
|
##### `lfm.artist.getTags(params, callback(err, tags))`
|
|
|
|
See [docs](http://www.last.fm/api/show/artist.getTags) for params.
|
|
|
|
##### `lfm.artist.getTopAlbums(params, callback(err, topAlbums))`
|
|
|
|
See [docs](http://www.last.fm/api/show/artist.getTopAlbums) for params.
|
|
|
|
##### `lfm.artist.getTopTags(params, callback(err, topTags))`
|
|
|
|
See [docs](http://www.last.fm/api/show/artist.getTopTags) for params.
|
|
|
|
##### `lfm.artist.getTopTracks(params, callback(err, topTracks))`
|
|
|
|
See [docs](http://www.last.fm/api/show/artist.getTopTracks) for params.
|
|
|
|
##### `lfm.artist.removeTag(artist, tag, callback(err))`
|
|
|
|
See [docs](http://www.last.fm/api/show/artist.removeTag).
|
|
|
|
##### `lfm.artist.search(params, callback(err, results))`
|
|
|
|
See [docs](http://www.last.fm/api/show/artist.search) for params.
|
|
|
|
### Auth
|
|
|
|
##### `lfm.auth.getMobileSession(username, password, callback(err, session))`
|
|
|
|
See [docs](http://www.last.fm/api/show/auth.getMobileSession).
|
|
|
|
##### `lfm.auth.getSession(token, callback(err, session))`
|
|
|
|
See [docs](http://www.last.fm/api/show/auth.getSession).
|
|
|
|
##### `lfm.auth.getToken(callback(err, token))`
|
|
|
|
See [docs](http://www.last.fm/api/show/auth.getToken).
|
|
|
|
###Chart
|
|
|
|
##### `lfm.chart.getTopArtists([params,] callback(err, artists))`
|
|
|
|
See [docs](http://www.last.fm/api/show/chart.getTopArtists) for params. `params` is optional.
|
|
|
|
##### `lfm.chart.getTopTags([params,] callback(err, tags))`
|
|
|
|
See [docs](http://www.last.fm/api/show/chart.getTopTags) for params. `params` is optional.
|
|
|
|
##### `lfm.chart.getTopTracks([params,] callback(err, tracks))`
|
|
|
|
See [docs](http://www.last.fm/api/show/chart.getTopTracks) for params. `params` is optional.
|
|
|
|
### Geo
|
|
|
|
##### `lfm.geo.getTopArtists(params, callback(err, topArtists))`
|
|
|
|
See [docs](http://www.last.fm/api/show/geo.getTopArtists) for params.
|
|
|
|
##### `lfm.geo.getTopTracks(params, callback(err, topTracks))`
|
|
|
|
See [docs](http://www.last.fm/api/show/geo.getTopTracks) for params.
|
|
|
|
### Library
|
|
|
|
##### `lfm.library.getArtists(params, callback(err, artists))`
|
|
|
|
See [docs](http://www.last.fm/api/show/library.getArtists) for params.
|
|
|
|
### Tag
|
|
|
|
##### `lfm.tag.getInfo(tag, [lang,] callback(err, tag))`
|
|
|
|
See [docs](http://www.last.fm/api/show/tag.getInfo). `lang` is optional and, if provided, must be an ISO 639 alpha-2 language code.
|
|
|
|
##### `lfm.tag.getSimilar(tag, callback(err, similarTags))`
|
|
|
|
See [docs](http://www.last.fm/api/show/tag.getSimilar).
|
|
|
|
##### `lfm.tag.getTopAlbums(params, callback(err, topAlbums))`
|
|
|
|
See [docs](http://www.last.fm/api/show/tag.getTopAlbums) for params.
|
|
|
|
##### `lfm.tag.getTopArtists(params, callback(err, topArtists))`
|
|
|
|
See [docs](http://www.last.fm/api/show/tag.getTopArtists) for params.
|
|
|
|
##### `lfm.tag.getTopTags(callback(err, topTags))`
|
|
|
|
See [docs](http://www.last.fm/api/show/tag.getTopTags).
|
|
|
|
##### `lfm.tag.getTopTracks(params, callback(err, topTracks))`
|
|
|
|
See [docs](http://www.last.fm/api/show/tag.getTopTracks) for params.
|
|
|
|
##### `lfm.tag.getWeeklyChartList(tag, callback(err, weeklyChartList))`
|
|
|
|
See [docs](http://www.last.fm/api/show/tag.getWeeklyChartList).
|
|
|
|
### Track
|
|
|
|
##### `lfm.track.addTags(artist, track, tags, callback(err))`
|
|
|
|
See [docs](http://www.last.fm/api/show/track.addTags). `tags` can be a string or an array.
|
|
|
|
##### `lfm.track.getCorrection(artist, track, callback(err, corrections))`
|
|
|
|
See [docs](http://www.last.fm/api/show/track.getCorrection).
|
|
|
|
##### `lfm.track.getInfo(params, callback(err, track))`
|
|
|
|
See [docs](http://www.last.fm/api/show/track.getInfo) for params.
|
|
|
|
##### `lfm.track.getSimilar(params, callback(err, similarTracks))`
|
|
|
|
See [docs](http://www.last.fm/api/show/track.getSimilar) for params.
|
|
|
|
##### `lfm.track.getTags(params, callback(err, tags))`
|
|
|
|
See [docs](http://www.last.fm/api/show/track.getTags) for params.
|
|
|
|
##### `lfm.track.getTopTags(params, callback(err, topTags))`
|
|
|
|
See [docs](http://www.last.fm/api/show/track.getTopTags) for params.
|
|
|
|
##### `lfm.track.love(params, callback(err))`
|
|
|
|
See [docs](http://www.last.fm/api/show/track.love) for params.
|
|
|
|
##### `lfm.track.removeTag(artist, track, tag, callback(err))`
|
|
|
|
See [docs](http://www.last.fm/api/show/track.removeTag).
|
|
|
|
##### `lfm.track.scrobble(params, callback(err, scrobbles))`
|
|
|
|
See [docs](http://www.last.fm/api/show/track.scrobble) for params.
|
|
`params` can be an array of scrobble parameters to scrobble multiple
|
|
tracks at once.
|
|
|
|
##### `lfm.track.search(params, callback(err, results))`
|
|
|
|
See [docs](http://www.last.fm/api/show/track.search) for params.
|
|
|
|
##### `lfm.track.unlove(artist, track, callback(err))`
|
|
|
|
See [docs](http://www.last.fm/api/show/track.unlove).
|
|
|
|
##### `lfm.track.updateNowPlaying(params, callback(err, nowPlaying))`
|
|
|
|
See [docs](http://www.last.fm/api/show/track.updateNowPlaying) for params.
|
|
|
|
### User
|
|
|
|
##### `lfm.user.getArtistTracks(params, callback(err, artistTracks))`
|
|
|
|
See [docs](http://www.last.fm/api/show/user.getArtistTracks) for params.
|
|
|
|
##### `lfm.user.getFriends(params, callback(err, friends))`
|
|
|
|
See [docs](http://www.last.fm/api/show/user.getFriends) for params.
|
|
|
|
##### `lfm.user.getInfo([user,] callback(err, info))`
|
|
|
|
See [docs](http://www.last.fm/api/show/user.getInfo). `user` is optional. However, authentication is required if omitted.
|
|
|
|
##### `lfm.user.getLovedTracks(params, callback(err, lovedTracks))`
|
|
|
|
See [docs](http://www.last.fm/api/show/user.getLovedTracks) for params.
|
|
|
|
##### `lfm.user.getPersonalTags(params, callback(err, taggings))`
|
|
|
|
See [docs](http://www.last.fm/api/show/user.getPersonalTags) for params.
|
|
|
|
##### `lfm.user.getRecentTracks(params, callback(err, recentTracks))`
|
|
|
|
See [docs](http://www.last.fm/api/show/user.getRecentTracks) for params.
|
|
|
|
##### `lfm.user.getTopAlbums(params, callback(err, topAlbums))`
|
|
|
|
See [docs](http://www.last.fm/api/show/user.getTopAlbums) for params.
|
|
|
|
##### `lfm.user.getTopArtists(params, callback(err, topArtists))`
|
|
|
|
See [docs](http://www.last.fm/api/show/user.getTopArtists) for params.
|
|
|
|
##### `lfm.user.getTopTags(user, [limit,] callback(err, topTags))`
|
|
|
|
See [docs](http://www.last.fm/api/show/user.getTopTags). `limit` is optional.
|
|
|
|
##### `lfm.user.getTopTracks(params, callback(err, topTracks))`
|
|
|
|
See [docs](http://www.last.fm/api/show/user.getTopTracks) for params.
|
|
|
|
##### `lfm.user.getWeeklyAlbumChart(params, callback(err, weeklyAlbumChart))`
|
|
|
|
See [docs](http://www.last.fm/api/show/user.getWeeklyAlbumChart) for params.
|
|
|
|
##### `lfm.user.getWeeklyArtistChart(params, callback(err, weeklyArtistChart))`
|
|
|
|
See [docs](http://www.last.fm/api/show/user.getWeeklyArtistChart) for params.
|
|
|
|
##### `lfm.user.getWeeklyChartList(user, callback(err, weeklyChartList))`
|
|
|
|
See [docs](http://www.last.fm/api/show/user.getWeeklyChartList).
|
|
|
|
##### `lfm.user.getWeeklyTrackChart(params, callback(err, weeklyTrackChart))`
|
|
|
|
See [docs](http://www.last.fm/api/show/user.getWeeklyTrackChart) for params.
|
|
|
|
Contributors
|
|
------------
|
|
|
|
- [Max Kueng](https://github.com/maxkueng)
|
|
- [Aliou Diallo](https://github.com/aliou)
|
|
- [Jiri Bakker](https://github.com/JiriBakker)
|
|
|
|
License
|
|
-------
|
|
|
|
Copyright (c) 2013 Max Kueng
|
|
Licensed under the MIT license.
|
|
|
|
|
|
[lastfmnode]: https://github.com/jammus/lastfm-node
|
|
[semver]: http://semver.org/
|
|
[register]: http://www.last.fm/api/account/create
|
|
[webauth]: http://www.last.fm/api/webauth
|