lastfmapi

A Last.fm API client library wrapper with a simple and clean interface.

LastfmAPI

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 (errtrack) {
    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 (errsession) {
    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 (errscrobbles) {
    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.

Undocumented

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.

Copyright (c) 2013 Max Kueng Licensed under the MIT license.