lastfmapi

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

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
lastfmapi
5220.1.18 years ago11 years agoMinified + gzip package size for lastfmapi in KB

Readme

LastfmAPI
This is a wrapper library for James' lastfm-nodelastfmnode 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 Versioningsemver 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 hereregister.

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 herewebauth.
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/?apikey=YOURAPIKEY&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
AUTHENTICATIONTOKEN"
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-nodelastfmnode 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.