Skip to content

Latest commit

 

History

History
202 lines (115 loc) · 7.87 KB

README.md

File metadata and controls

202 lines (115 loc) · 7.87 KB
Raw

last-fm travis npm downloads

Simple, robust LastFM API client (for public data)

Install

npm install last-fm

Why this package?

The most useful data on LastFM is the public music data. When building an app that incorporates music data from LastFM, lots of functionality provided by the LastFM API isn't necessary – authorizing as a user, liking tracks, adding/removing tags, getting a list of songs in the user's "library", etc.

This package only provides the LastFM API methods that use GET requests to fetch data, making it smaller and simpler than the other LastFM libraries.

If this matches your use case, consider using this package.

Features

  • Powered by the LastFM API
  • Lightweight library, only provides the GET methods from the Last.fm API

Usage

First, get an API key from Last.fm.

const LastFM = require('last-fm')
const lastfm = new LastFM('API_KEY', { userAgent: 'MyApp/1.0.0 (http://example.com)' })

lastfm.trackSearch({ q: 'the greatest' }, (err, data) => {
  if (err) console.error(err)
  else console.log(data)
})

API

lastfm = new LastFM(key, [opts])

Create a new LastFM API client with the given public API key.

Since all the LastFM calls supported by this module access public data, the secret key is not required.

If opts is provided, it can contain the following options:

  • opts.userAgent - String to use as the User-Agent header in http requests
  • opts.minArtistListeners - Exclude artist results with fewer than this number of "listeners" (default: 0)
  • opts.minTrackListeners - Exclude track results with fewer than this number of "listeners" (default: 0)

Note: Unfortunately, there is no opts.minAlbumListeners since the Last.fm API does not include listener numbers in album results (even though the data exists when you get an individual album via lastfm.albumInfo)

Convenience API

These APIs are not part of the LastFM documentation, but they use data from the API and process it into a more useful form.

lastfm.search(opts, (err, data) => {})

Search for artists, tracks, or albums by name. (album.search, artist.search, track.search)

This returns the "top result" across all result types, prioritizing an exact query match, if one exists. Otherwise, the most popular result by number of "listeners" is used.

  • opts.q - the search query
  • opts.limit - the number of each type of result to fetch

Album API

lastfm.albumInfo(opts, (err, data) => {})

Get the metadata and tracklist for an album on Last.fm using the album name. (album.getInfo)

lastfm.albumTopTags(opts, (err, data) => {})

Get the top tags for an album on Last.fm, ordered by popularity. (album.getTopTags)

lastfm.albumSearch(opts, (err, data) => {})

Search for an album by name. Returns album matches sorted by relevance. (album.search)

Artist API

lastfm.artistCorrection(opts, (err, data) => {})

Use the last.fm corrections data to check whether the supplied artist has a correction to a canonical artist. (artist.getCorrection)

lastfm.artistInfo(opts, (err, data) => {})

Get the metadata for an artist. Includes biography, truncated at 300 characters. (artist.getInfo)

lastfm.artistSimilar(opts, (err, data) => {})

Get all the artists similar to this artist (artist.getSimilar)

lastfm.artistTopAlbums(opts, (err, data) => {})

Get the top albums for an artist on Last.fm, ordered by popularity. (artist.getTopAlbums)

lastfm.artistTopTags(opts, (err, data) => {})

Get the top tags for an artist on Last.fm, ordered by popularity. (artist.getTopTags)

lastfm.artistTopTracks(opts, (err, data) => {})

Get the top tracks by an artist on Last.fm, ordered by popularity. (artist.getTopTracks)

lastfm.artistSearch(opts, (err, data) => {})

Search for an artist by name. Returns artist matches sorted by relevance. (artist.search)

Chart API

lastfm.chartTopArtists(opts, (err, data) => {})

Get the top artists chart. (chart.getTopArtists)

lastfm.chartTopTags(opts, (err, data) => {})

Get the top tags chart. (chart.getTopTags)

lastfm.chartTopTracks(opts, (err, data) => {})

Get the top tracks chart. (chart.getTopTracks)

Geo API

lastfm.geoTopArtists(opts, (err, data) => {})

Get the most popular artists on Last.fm by country. (geo.getTopArtists)

lastfm.geoTopTracks(opts, (err, data) => {})

Get the most popular tracks on Last.fm last week by country. (geo.getTopTracks)

Tag API

lastfm.tagInfo(opts, (err, data) => {})

Get the metadata for a tag. (tag.getInfo)

lastfm.tagSimilar(opts, (err, data) => {})

Search for tags similar to this one. Returns tags ranked by similarity, based on listening data. (tag.getSimilar)

lastfm.tagTopAlbums(opts, (err, data) => {})

Get the top albums tagged by this tag, ordered by tag count. (tag.getTopAlbums)

lastfm.tagTopArtists(opts, (err, data) => {})

Get the top artists tagged by this tag, ordered by tag count. (tag.getTopArtists)

lastfm.tagTopTags(opts, (err, data) => {})

Fetches the top global tags on Last.fm, sorted by popularity (number of times used). (tag.getTopTags)

lastfm.tagTopTracks(opts, (err, data) => {})

Get the top tracks tagged by this tag, ordered by tag count. (tag.getTopTracks)

Track API

lastfm.trackCorrection(opts, (err, data) => {})

Use the last.fm corrections data to check whether the supplied track has a correction to a canonical track. (track.getCorrection)

lastfm.trackInfo(opts, (err, data) => {})

Get the metadata for a track on Last.fm using the artist/track name. (track.getInfo)

lastfm.trackSimilar(opts, (err, data) => {})

Get the similar tracks for this track on Last.fm, based on listening data. (track.getSimilar)

lastfm.trackTopTags(opts, (err, data) => {})

Get the top tags for this track on Last.fm, ordered by tag count. Supply a track & artist name. (track.getTopTags)

lastfm.trackSearch(opts, (err, data) => {})

Search for a track by track name. Returns track matches sorted by relevance. (track.search)

License

MIT. Copyright (c) Feross Aboukhadijeh.