README.md

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.

Getting Started

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.

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.

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');

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 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)

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 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 | Artist | Auth | Chart | Geo | Library | Tag | Track | User

Album

lfm.album.addTags(artist, album, tags, callback(err))

See docs. tags can be a string or an array.

lfm.album.getInfo(params, callback(err, album))

See docs for params.

lfm.album.getTags(params, callback(err, tags))

See docs for params.

lfm.album.getTopTags(params, callback(err, toptags))

See docs for params.

lfm.album.removeTag(artist, album, tag, callback(err))

See docs.

lfm.album.search(params, callback(err, results))

See docs for params.

Artist

lfm.artist.addTags(artist, tags, callback(err))

See docs. tags can be a string or an array.

lfm.artist.getCorrection(artist, callback(err, corrections))

See docs.

lfm.artist.getInfo(params, callback(err, artist))

See docs for params.

lfm.artist.getSimilar(params, callback(err, similarArtists))

See docs for params.

lfm.artist.getTags(params, callback(err, tags))

See docs for params.

lfm.artist.getTopAlbums(params, callback(err, topAlbums))

See docs for params.

lfm.artist.getTopTags(params, callback(err, topTags))

See docs for params.

lfm.artist.getTopTracks(params, callback(err, topTracks))

See docs for params.

lfm.artist.removeTag(artist, tag, callback(err))

See docs.

lfm.artist.search(params, callback(err, results))

See docs for params.

Auth

lfm.auth.getMobileSession(username, password, callback(err, session))

See docs.

lfm.auth.getSession(token, callback(err, session))

See docs.

lfm.auth.getToken(callback(err, token))

See docs.

###Chart

lfm.chart.getTopArtists([params,] callback(err, artists))

See docs for params. params is optional.

lfm.chart.getTopTags([params,] callback(err, tags))

See docs for params. params is optional.

lfm.chart.getTopTracks([params,] callback(err, tracks))

See docs for params. params is optional.

Geo

lfm.geo.getTopArtists(params, callback(err, topArtists))

See docs for params.

lfm.geo.getTopTracks(params, callback(err, topTracks))

See docs for params.

Library

lfm.library.getArtists(params, callback(err, artists))

See docs for params.

Tag

lfm.tag.getInfo(tag, [lang,] callback(err, tag))

See docs. lang is optional and, if provided, must be an ISO 639 alpha-2 language code.

lfm.tag.getSimilar(tag, callback(err, similarTags))

See docs.

lfm.tag.getTopAlbums(params, callback(err, topAlbums))

See docs for params.

lfm.tag.getTopArtists(params, callback(err, topArtists))

See docs for params.

lfm.tag.getTopTags(callback(err, topTags))

See docs.

lfm.tag.getTopTracks(params, callback(err, topTracks))

See docs for params.

lfm.tag.getWeeklyChartList(tag, callback(err, weeklyChartList))

See docs.

Track

lfm.track.addTags(artist, track, tags, callback(err))

See docs. tags can be a string or an array.

lfm.track.getCorrection(artist, track, callback(err, corrections))

See docs.

lfm.track.getInfo(params, callback(err, track))

See docs for params.

lfm.track.getSimilar(params, callback(err, similarTracks))

See docs for params.

lfm.track.getTags(params, callback(err, tags))

See docs for params.

lfm.track.getTopTags(params, callback(err, topTags))

See docs for params.

lfm.track.love(params, callback(err))

See docs for params.

lfm.track.removeTag(artist, track, tag, callback(err))

See docs.

lfm.track.scrobble(params, callback(err, scrobbles))

See docs 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 for params.

lfm.track.unlove(artist, track, callback(err))

See docs.

lfm.track.updateNowPlaying(params, callback(err, nowPlaying))

See docs for params.

User

lfm.user.getArtistTracks(params, callback(err, artistTracks))

See docs for params.

lfm.user.getFriends(params, callback(err, friends))

See docs for params.

lfm.user.getInfo([user,] callback(err, info))

See docs. user is optional. However, authentication is required if omitted.

lfm.user.getLovedTracks(params, callback(err, lovedTracks))

See docs for params.

lfm.user.getPersonalTags(params, callback(err, taggings))

See docs for params.

lfm.user.getRecentTracks(params, callback(err, recentTracks))

See docs for params.

lfm.user.getTopAlbums(params, callback(err, topAlbums))

See docs for params.

lfm.user.getTopArtists(params, callback(err, topArtists))

See docs for params.

lfm.user.getTopTags(user, [limit,] callback(err, topTags))

See docs. limit is optional.

lfm.user.getTopTracks(params, callback(err, topTracks))

See docs for params.

lfm.user.getWeeklyAlbumChart(params, callback(err, weeklyAlbumChart))

See docs for params.

lfm.user.getWeeklyArtistChart(params, callback(err, weeklyArtistChart))

See docs for params.

lfm.user.getWeeklyChartList(user, callback(err, weeklyChartList))

See docs.

lfm.user.getWeeklyTrackChart(params, callback(err, weeklyTrackChart))

See docs for params.

Contributors

• Max Kueng
• Aliou Diallo
• Jiri Bakker

License

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