Last.Fm Node Client
This is a Node.js JavaScript library for interfacing with the Last.fm API.
- Consistent: Providing you a uniform set of abstractions that allows you to use the interface predictably and reliably.
- Versatile: Adapting it's communication with the API, complying with it's specifications without you needing to adapt your code.
- Low level: Delivering you the response as it comes directly from the API, using it's native
format
parameter, to deliver a consistent JSON response.
See the Last.Fm API web page for information about the Last.Fm API, including details on how to register an account and get your API key, shared secret, and session key.
Installation
$ npm install lastfm-node-client
Node.js 7.0.0 or later is required.
Usage
First, you must instantiate the LastFm Class with an object parameter containing the details of your API account. apiKey
is required, however since many endpoints of the API do not require authentication, secret
and sessionKey
are optional.
const LastFm = require("lastfm-node-client");
const lastFm = new LastFm({
"apiKey": "API_KEY",
"secret": "SECRET",
"sessionKey": "SESSION_KEY"
});
Making requests
The Last.fm API is structured into packages and methods, accessed as Package.method
. The LastFm Class contains directly corresponding methods for each package method, written as lastFm.packageMethod()
. For example, endpoint User.getRecentTracks
is accessed as lastFm.userGetRecentTracks()
.
lastFm.userGetRecentTracks();
Parameters can be passed to the API through the params
argument as an object that will be sent directly with the request, either as a query for a GET request, or a body for a POST request. The property names will not be transformed or abstracted, and so they must match the endpoint parameters exactly.
Note: Endpoints Auth.getToken
and Tag.getTopTags
do not require additional parameters, as such, methods lastFm.authGetToken()
and lastFm.tagGetTopTags()
do not accept a params
argument.
lastFm.userGetRecentTracks({
"user": "USER"
});
Capturing responses
Every method returns a promise of the pending request by default. To access the response, you can chain .then()
to the method, or use await
.
Chaining .then()
:
lastFm.userGetRecentTracks({
"user": "USER"
})
.then(data => {
console.log(data);
};
Using await
:
const data = await lastFm.userGetRecentTracks({
"user": "USER"
});
console.log(data);
An optional callback can be passed as the last argument. It is invoked with conventional (err, data)
parameters; err
being any exceptions thrown in the event of an error, data
containing the JSON response of the API upon success.
Note: "Success" in this context means a successful request, however the API may return an error response for a number of reasons detailed in their error codes documentation.
lastFm.userGetRecentTracks({
"user": "USER"
},
(err, data)) => {
console.log(data);
});
When callback is passed, methods do not return a promise
, instead return the LastFm instance the method was called on. This allows you to chain requests.
Utility methods
These methods do not correspond to an exact API endpoint, but are abstractions of the already provided methods to provide easier usage.
lastFm.trackScrobbleMany
This method takes an array of objects that match the params
parameter accepted by lastFm.trackScrobble
. It allows for multiple tracks to be submitted to the API in one request.
lastFm.trackScrobbleMany([
{
"artist": "ARTIST",
"album": "ALBUM",
"track": "TRACK",
"timestamp": "TIMESTAMP"
},
{
"artist": "ARTIST",
"album": "ALBUM",
"track": "TRACK",
"timestamp": "TIMESTAMP"
}
]);