https://github.com/mannuelf/lastfm-nodejs-client
A Node JS client for interacting with the LastFm API
https://github.com/mannuelf/lastfm-nodejs-client
api api-client lastfm nodejs typescript
Last synced: 3 months ago
JSON representation
A Node JS client for interacting with the LastFm API
- Host: GitHub
- URL: https://github.com/mannuelf/lastfm-nodejs-client
- Owner: mannuelf
- License: mit
- Created: 2022-10-28T04:51:17.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-03-27T06:31:22.000Z (3 months ago)
- Last Synced: 2026-03-27T17:47:06.872Z (3 months ago)
- Topics: api, api-client, lastfm, nodejs, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/lastfm-nodejs-client
- Size: 569 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# LastFm NodeJs client
[](https://www.npmjs.com/package/lastfm-nodejs-client)
[](https://www.npmjs.com/package/lastfm-nodejs-client)
[](https://www.codacy.com/gh/mannuelf/lastfm-nodejs-client/dashboard?utm_source=github.com&utm_medium=referral&utm_content=mannuelf/lastfm-nodejs-client&utm_campaign=Badge_Grade)
[](https://opensource.org/licenses/MIT)
A TypeScript client for the [Last.fm API](https://www.last.fm/api). Works in Node.js ≥18 and all modern browsers — no polyfills required.
## Why use this
**Zero dependencies.** The library ships no third-party runtime dependencies. HTTP requests use the native `fetch` API built into Node.js ≥18, and API signatures are generated with the built-in `node:crypto` module. Installing it won't bloat your `node_modules` or introduce supply-chain risk.
**Fully typed.** Every API response has a hand-written TypeScript interface, so you get autocomplete and type safety straight out of the box — no extra `@types` packages needed.
**Dual ESM + CJS.** The package ships both ES module and CommonJS builds, so it works in any Node.js project regardless of whether you use `import` or `require`.
## Install
```bash
pnpm add lastfm-nodejs-client
```
```bash
npm install lastfm-nodejs-client
```
```bash
yarn add lastfm-nodejs-client
```
```bash
bun add lastfm-nodejs-client
```
```ts
// Deno
import LastFmApi from 'jsr:@mannuelf/lastfm-nodejs-client';
```
## Setup
Create a `.env` file in your project root:
```bash
LASTFM_API_BASE_URL="https://ws.audioscrobbler.com/2.0/"
LASTFM_USER="your_username"
LASTFM_API_KEY="your_api_key"
LASTFM_APPNAME="your_app_name"
LASTFM_SHARED_SECRET="your_shared_secret"
```
Get your API key at [last.fm/api/account/create](https://www.last.fm/api/account/create).
## Usage
```ts
import LastFmApi from 'lastfm-nodejs-client';
const lastFm = LastFmApi();
const { method } = lastFm;
```
### Get a user's top artists
```ts
import LastFmApi from 'lastfm-nodejs-client';
import type { TopArtistsResponse } from 'lastfm-nodejs-client';
const lastFm = LastFmApi();
const { method } = lastFm;
const data: TopArtistsResponse = await lastFm.getTopArtists(
method.user.getTopArtists,
'your_username',
'overall', // period: overall | 7day | 1month | 3month | 6month | 12month
'10', // limit
);
console.log(data.topartists.artist);
```
### Get a user's recent tracks
```ts
import LastFmApi from 'lastfm-nodejs-client';
import type { RecentTracksResponse } from 'lastfm-nodejs-client';
const lastFm = LastFmApi();
const { method } = lastFm;
const data: RecentTracksResponse = await lastFm.getRecentTracks(
method.user.getRecentTracks,
'your_username',
'10', // limit
);
console.log(data.recenttracks.track);
```
### Get artist info
```ts
import LastFmApi from 'lastfm-nodejs-client';
import type { ArtistInfoResponse } from 'lastfm-nodejs-client';
const lastFm = LastFmApi();
const { method } = lastFm;
const data: ArtistInfoResponse = await lastFm.artist.artistGetInfo(
method.artist.getInfo,
'Radiohead',
);
console.log(data.artist);
```
### Get album info
```ts
import LastFmApi from 'lastfm-nodejs-client';
import type { AlbumInfoResponse } from 'lastfm-nodejs-client';
const lastFm = LastFmApi();
const { method } = lastFm;
const data: AlbumInfoResponse = await lastFm.album.albumGetInfo(
method.album.getInfo,
'Radiohead',
'OK Computer',
);
console.log(data.album);
```
### Search for a track
```ts
import LastFmApi from 'lastfm-nodejs-client';
import type { TrackSearchResponse } from 'lastfm-nodejs-client';
const lastFm = LastFmApi();
const { method } = lastFm;
const data: TrackSearchResponse = await lastFm.track.trackSearch(
method.track.search,
'Creep',
'Radiohead', // optional artist filter
'5', // limit
);
console.log(data.results.trackmatches.track);
```
### Love a track (authenticated)
Requires a session key (`sk`) obtained via `auth.getMobileSession` or `auth.getSession`.
```ts
import LastFmApi from 'lastfm-nodejs-client';
const lastFm = LastFmApi();
const { method } = lastFm;
await lastFm.track.trackLove(method.track.love, 'Radiohead', 'Creep', 'your_session_key');
```
## All available namespaces
| Namespace | Methods |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `album` | `albumGetInfo`, `albumGetTags`, `albumGetTopTags`, `albumSearch`, `albumAddTags`, `albumRemoveTag` |
| `artist` | `artistGetInfo`, `artistGetSimilar`, `artistGetTags`, `artistGetTopAlbums`, `artistGetTopTags`, `artistGetTopTracks`, `artistSearch`, `artistAddTags`, `artistRemoveTag`, `artistGetCorrection` |
| `auth` | `getToken`, `getSession`, `getMobileSession` |
| `chart` | `chartTopArtists`, `chartTopTracks`, `chartTopTags` |
| `geo` | `geoGetTopArtists`, `geoGetTopTracks` |
| `library` | `libraryGetArtists` |
| `tag` | `tagGetInfo`, `tagGetSimilar`, `tagGetTopAlbums`, `tagGetTopArtists`, `tagGetTopTags`, `tagGetWeeklyChartList`, `tagTopTracks` |
| `track` | `trackGetInfo`, `trackGetSimilar`, `trackGetTags`, `trackGetTopTags`, `trackSearch`, `trackLove`, `trackUnlove`, `trackAddTags`, `trackRemoveTag`, `trackScrobble`, `trackUpdateNowPlaying`, `trackGetCorrection` |
| `user` | `userGetPersonalTags` |
Legacy flat methods also available: `getTopArtists`, `getTopTracks`, `getRecentTracks`, `getLovedTracks`, `getInfo`, `getFriends`, `getUserTopTags`, `getWeeklyAlbumChart`, `getWeeklyArtistChart`, `getWeeklyChartList`, `getWeeklyTrackChart`, `getTopAlbums`.
## Developing
```bash
gh repo fork mannuelf/lastfm-nodejs-client
```
```bash
pnpm install
pnpm test
pnpm lint
pnpm build
```
### Why I built this
I was building a scrobbles page at [mannuelferreira.com/scrobbles](https://mannuelferreira.com/scrobbles) and thought others might find it useful.