This is a wrapper library for James' lastfm-node 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.
Install with npm
npm install lastfmapi
or add it to the dependencies
array in your package.json file. This
module follows the Semantic Versioning guidelines so you can
expect all sub-versions of the same major version to have a compatible
API.
Use require
to load the module
var LastfmAPI = require('lastfmapi');
and create a new instance as follows:
var lfm = new LastfmAPI({
'api_key' : 'YOUR_API_KEY',
'secret' : 'YOUR_API_SECRET'
});
Try it out:
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.
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.
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.
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:
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:
lfm.setSessionCredentials('LASTFM_USERNAME', 'THE_USER_SESSION_KEY');
(Coming soon)
(Coming soon)
This example requires authentication and assumes you have your session credentials at-the-ready. Look at the authentication example to see how it works.
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)
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.
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
Exposes the underlying lastfm-node API client so you can go "low-level" if you like
Constructs and returns an authentication URL. The params object has 2
optional properties: cb
is the callback URL and token
is an
authentication token
Fetches a Last.fm session and stores the session credentials in the object
Stores session credentials that will be used to make API calls that require authentication
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 | Artist | Auth | Chart | Event | Geo | Group | Library | Playlist | Radio | Tag | Tasteometer | Track | User | Venue
See docs. tags
can be a string or an array.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs.
See docs for params.
See docs for params.
See docs. tags
can be a string or an array.
See docs.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs.
See docs for params.
See docs for params. params.recipient
can be a string or an array.
See docs.
See docs.
See docs.
See docs.
###Chart
See docs for params. params
is optional.
See docs for params. params
is optional.
See docs for params. params
is optional.
See docs for params. params
is optional.
See docs for params. params
is optional.
See docs for params. params
is optional.
See docs for status
.
See docs for params.
See docs.
See docs for params.
See docs for params. params.recipient
can be a string or an array.
See docs.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs.
See docs. country
is optional and, if provided, must be an ISO 3166-1 country name.
See docs for params.
See docs for params.
See docs.
See docs for params.
See docs for params.
See docs for params.
See docs.
See docs for params.
See docs.
See docs.
See docs.
See docs for params.
See docs for params.
See docs for params.
See docs.
See docs.
See docs.
See docs.
See docs.
See docs for params. params
is optional.
Note: The radio methods have not been tested because Last.fm Radio is no longer available in my country.
See docs for params. params
is optional.
See docs.
See docs. lang
is optional and, if provided, must be an ISO 639 alpha-2 language code.
See docs. lang
is optional and, if provided, must be an ISO 639 alpha-2 language code.
See docs.
See docs for params.
See docs for params.
See docs.
See docs for params.
See docs for params.
See docs.
See docs for params.
See docs for params.
See docs. tags
can be a string or an array.
See docs for params.
See docs.
See docs.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs.
See docs for params.
params
can be an array of scrobble parameters to scrobble multiple
tracks at once.
See docs for params.
See docs for params. params.recipient
can be a string or an array.
See docs.
See docs.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs. user
is optional. However, authentication is required if omitted.
See docs for params.
See docs. limit
is optional.
See docs for params. useRecs
is optional.
See docs for params.
See docs for params.
See docs.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs for params.
See docs. limit
is optional.
See docs for params.
See docs for params.
See docs for params.
See docs.
See docs for params.
See docs.
See docs. festivalsOnly
is optional.
See docs for params.
- Max Kueng (http://maxkueng.com/)
- Aliou Diallo (http://aliou.me/)
Copyright (c) 2013 Max Kueng Licensed under the MIT license.