Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/exogen/graphbrainz-extension-lastfm

Last.fm GraphQL extension for GraphBrainz.
https://github.com/exogen/graphbrainz-extension-lastfm

graphbrainz graphql graphql-schema lastfm lastfm-api musicbrainz musicbrainz-api

Last synced: about 1 month ago
JSON representation

Last.fm GraphQL extension for GraphBrainz.

Awesome Lists containing this project

README 

          
# GraphBrainz Extension: Last.fm



[![build status](https://img.shields.io/travis/exogen/graphbrainz-extension-lastfm/master.svg)](https://travis-ci.org/exogen/graphbrainz-extension-lastfm)

[![coverage](https://img.shields.io/codecov/c/github/exogen/graphbrainz-extension-lastfm.svg)](https://codecov.io/gh/exogen/graphbrainz-extension-lastfm)

[![npm version](https://img.shields.io/npm/v/graphbrainz-extension-lastfm.svg)](https://www.npmjs.com/package/graphbrainz-extension-lastfm)

[![license](https://img.shields.io/npm/l/graphbrainz-extension-lastfm.svg)](https://github.com/exogen/graphbrainz-extension-lastfm/blob/master/LICENSE)



Retrieve artist, release, and recording information from [Last.fm][].



The extension works by sending the MBIDs of entities to the [Last.fm API][]

whenever their `lastFM` field is requested. Only entities with known MBIDs on

Last.fm will have their `lastFM` field, otherwise it will be null.



**[Try out the live demo!][demo]** :bulb: Use the “Docs” sidebar or the

documentation below to help construct your query.



## Installation



To use this extension, install [GraphBrainz][] then:



```console

$ npm install graphbrainz-extension-lastfm

$ GRAPHBRAINZ_EXTENSIONS='["graphbrainz-extension-lastfm"]' graphbrainz

```



Or, if you are using the middleware directly:



```js

import graphbrainz from 'graphbrainz'



const middleware = graphbrainz({

  // Don't forget to add the other extensions you use, too.

  extensions: ['graphbrainz-extension-lastfm']

})

```



## Configuration



This extension can be configured using environment variables:



* **`LASTFM_API_KEY`**: The Last.fm API key to use. This is required for any

  fields added by the extension to successfully resolve.

* **`LASTFM_BASE_URL`**: The base URL at which to access the Last.fm API.

  Defaults to `http://ws.audioscrobbler.com/2.0/`.

* **`LASTFM_CACHE_SIZE`**: The number of items to keep in the cache. Defaults to

  `GRAPHBRAINZ_CACHE_SIZE` if defined, or `8192`.

* **`LASTFM_CACHE_TTL`**: The number of seconds to keep items in the cache.

  Defaults to `GRAPHBRAINZ_CACHE_TTL` if defined, or `86400000` (one day).



This extension uses its own cache, separate from the MusicBrainz loader cache.



## Example Queries



Find the MBIDs of similar recordings ([try it](https://graphbrainz-extension-lastfm.herokuapp.com/?query=%7B%0A%20%20search%20%7B%0A%20%20%20%20recordings(query%3A%20%22Dream%20Baby%20Dream%20artist%3ASuicide%22%2C%20first%3A%201)%20%7B%0A%20%20%20%20%20%20nodes%20%7B%0A%20%20%20%20%20%20%20%20mbid%0A%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20lastFM%20%7B%0A%20%20%20%20%20%20%20%20%20%20similarTracks(first%3A%205)%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20matchScore%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20mbid%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20artist%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20name%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A)):



```graphql

{

  search {

    recordings(query: "Dream Baby Dream artist:Suicide", first: 1) {

      nodes {

        mbid

        title

        lastFM {

          similarTracks(first: 5) {

            edges {

              matchScore

              node {

                mbid

                title

                artist {

                  name

                }

              }

            }

          }

        }

      }

    }

  }

}

```



## Schema Types



  Table of Contents



  * [Objects](#objects)

    * [Area](#area)

    * [Artist](#artist)

    * [LastFMAlbum](#lastfmalbum)

    * [LastFMAlbumConnection](#lastfmalbumconnection)

    * [LastFMAlbumEdge](#lastfmalbumedge)

    * [LastFMArtist](#lastfmartist)

    * [LastFMArtistConnection](#lastfmartistconnection)

    * [LastFMArtistEdge](#lastfmartistedge)

    * [LastFMChartQuery](#lastfmchartquery)

    * [LastFMCountry](#lastfmcountry)

    * [LastFMQuery](#lastfmquery)

    * [LastFMTag](#lastfmtag)

    * [LastFMTagConnection](#lastfmtagconnection)

    * [LastFMTagEdge](#lastfmtagedge)

    * [LastFMTrack](#lastfmtrack)

    * [LastFMTrackConnection](#lastfmtrackconnection)

    * [LastFMTrackEdge](#lastfmtrackedge)

    * [LastFMWikiContent](#lastfmwikicontent)

    * [Query](#query)

    * [Recording](#recording)

    * [Release](#release)

  * [Enums](#enums)

    * [LastFMImageSize](#lastfmimagesize)



### Objects



#### Area



:small_blue_diamond: *This type has been extended.

See the [base schema](https://github.com/exogen/graphbrainz/docs/types.md) for a description and additional fields.*



Field

Argument

Type

Description



lastFM

LastFMCountry



Chart data available for this area on [Last.fm](https://www.last.fm/), if

the area represents a country with an [ISO 3166 code](https://en.wikipedia.org/wiki/ISO_3166).

This field is provided by the Last.fm extension.



#### Artist



:small_blue_diamond: *This type has been extended.

See the [base schema](https://github.com/exogen/graphbrainz/docs/types.md) for a description and additional fields.*



Field

Argument

Type

Description



lastFM

LastFMArtist



Data about the artist from [Last.fm](https://www.last.fm/), a good source

for measuring popularity via listener and play counts. This field is

provided by the Last.fm extension.



#### LastFMAlbum



An album on [Last.fm](https://www.last.fm/) corresponding with a MusicBrainz

Release.



Field

Argument

Type

Description



mbid

MBID



The MBID of the corresponding MusicBrainz release.



title

String



The title of the album according to [Last.fm](https://www.last.fm/).



url

URLString!



The URL for the album on [Last.fm](https://www.last.fm/).



image

URLString



An image of the cover artwork of the release.



size

LastFMImageSize



The size of the image to retrieve.



listenerCount

Float



The number of listeners recorded for the album.



playCount

Float



The number of plays recorded for the album.



description

LastFMWikiContent



Historical information written about the album, often available in several

languages.



lang

String



The two-letter code for the language in which to retrieve the description.



artist

LastFMArtist



The artist who released the album. This returns the Last.fm artist info,

not the MusicBrainz artist.



topTags

LastFMTagConnection



A list of tags applied to the artist by users, ordered by popularity.



first

Int



The maximum number of tags to retrieve.



after

String



The cursor of the edge after which more tags will be retrieved.



#### LastFMAlbumConnection



A connection to a list of items.



Field

Argument

Type

Description



pageInfo

PageInfo!



Information to aid in pagination.



edges

[LastFMAlbumEdge]



A list of edges.



nodes

[LastFMAlbum]



A list of nodes in the connection (without going through the `edges` field).



totalCount

Int



A count of the total number of items in this connection, ignoring pagination.



#### LastFMAlbumEdge



An edge in a connection.



Field

Argument

Type

Description



node

LastFMAlbum



The item at the end of the edge.



cursor

String!



A cursor for use in pagination.



#### LastFMArtist



An artist on [Last.fm](https://www.last.fm/).



Field

Argument

Type

Description



mbid

MBID



The MBID of the corresponding MusicBrainz artist.



name

String



The name of the artist according to [Last.fm](https://www.last.fm/).



url

URLString!



The URL for the artist on [Last.fm](https://www.last.fm/).



image

URLString



An image of the artist.



size

LastFMImageSize



The size of the image to retrieve.



listenerCount

Float



The number of listeners recorded for the artist.



playCount

Float



The number of plays recorded for the artist.



similarArtists

LastFMArtistConnection



A list of similar artists.



first

Int



The maximum number of artists to retrieve.



after

String



The cursor of the edge after which more artists will be retrieved.



topAlbums

LastFMAlbumConnection



A list of the artist’s most popular albums.



first

Int



The maximum number of albums to retrieve.



after

String



The cursor of the edge after which more albums will be retrieved.



topTags

LastFMTagConnection



A list of tags applied to the artist by users, ordered by popularity.



first

Int



The maximum number of tags to retrieve.



after

String



The cursor of the edge after which more tags will be retrieved.



topTracks

LastFMTrackConnection



A list of the artist’s most popular tracks.



first

Int



The maximum number of tracks to retrieve.



after

String



The cursor of the edge after which more tracks will be retrieved.



biography

LastFMWikiContent



A biography of the artist, often available in several languages.



lang

String



The two-letter code for the language in which to retrieve the biography.



#### LastFMArtistConnection



A connection to a list of items.



Field

Argument

Type

Description



pageInfo

PageInfo!



Information to aid in pagination.



edges

[LastFMArtistEdge]



A list of edges.



nodes

[LastFMArtist]



A list of nodes in the connection (without going through the `edges` field).



totalCount

Int



A count of the total number of items in this connection, ignoring pagination.



#### LastFMArtistEdge



An edge in a connection.



Field

Argument

Type

Description



node

LastFMArtist



The item at the end of the edge.



cursor

String!



A cursor for use in pagination.



matchScore

Float



The artist similarity score (0–1) as determined by [Last.fm](https://www.last.fm/),

if this connection is with another artist.



#### LastFMChartQuery



A query for chart data on [Last.fm](https://www.last.fm/).



Field

Argument

Type

Description



topArtists

LastFMArtistConnection



The most popular artists, ordered by popularity. If a country code is

given, retrieve the most popular artists in that country.



country

String



A two-letter [ISO 3166 country code](https://en.wikipedia.org/wiki/ISO_3166).



first

Int



The maximum number of artists to retrieve.



after

String



The cursor of the edge after which more artists will be retrieved.



topTags

LastFMTagConnection



The most popular tags, ordered by popularity.



first

Int



The maximum number of tags to retrieve.



after

String



The cursor of the edge after which more tags will be retrieved.



topTracks

LastFMTrackConnection



The most popular tracks, ordered by popularity. If a country code is

given, retrieve the most popular tracks in that country.



country

String



A two-letter [ISO 3166 country code](https://en.wikipedia.org/wiki/ISO_3166).



first

Int



The maximum number of tracks to retrieve.



after

String



The cursor of the edge after which more tracks will be retrieved.



#### LastFMCountry



A country with chart data available on [Last.fm](https://www.last.fm/).



Field

Argument

Type

Description



topArtists

LastFMArtistConnection



The top artists in this country, ordered by popularity.



first

Int



The maximum number of artists to retrieve.



after

String



The cursor of the edge after which more artists will be retrieved.



topTracks

LastFMTrackConnection



The top tracks in this country, ordered by popularity.



first

Int



The maximum number of tracks to retrieve.



after

String



The cursor of the edge after which more tracks will be retrieved.



#### LastFMQuery



The different types of [Last.fm](https://www.last.fm/) queries that can be

made that are not connected to any particular MusicBrainz entity.



Field

Argument

Type

Description



chart

LastFMChartQuery!



A query for chart data.



#### LastFMTag



A tag added by users to an entity on [Last.fm](https://www.last.fm/).



Field

Argument

Type

Description



name

String!



The tag name.



url

URLString!



The URL for the tag on [Last.fm](https://www.last.fm/).



#### LastFMTagConnection



A connection to a list of items.



Field

Argument

Type

Description



pageInfo

PageInfo!



Information to aid in pagination.



edges

[LastFMTagEdge]



A list of edges.



nodes

[LastFMTag]



A list of nodes in the connection (without going through the `edges` field).



totalCount

Int



A count of the total number of items in this connection, ignoring pagination.



#### LastFMTagEdge



An edge in a connection.



Field

Argument

Type

Description



node

LastFMTag



The item at the end of the edge.



cursor

String!



A cursor for use in pagination.



tagCount

Int



The number of times the tag has been applied to the item in question.



#### LastFMTrack



A track on [Last.fm](https://www.last.fm/) corresponding with a MusicBrainz

Recording.



Field

Argument

Type

Description



mbid

MBID



The MBID of the corresponding MusicBrainz recording.



title

String



The title of the track according to [Last.fm](https://www.last.fm/).



url

URLString!



The URL for the track on [Last.fm](https://www.last.fm/).



duration

Duration



The length of the track.



listenerCount

Float



The number of listeners recorded for the track.



playCount

Float



The number of plays recorded for the track.



description

LastFMWikiContent



Historical information written about the track, often available in several

languages.



lang

String



The two-letter code for the language in which to retrieve the description.



artist

LastFMArtist



The artist who released the track. This returns the Last.fm artist info,

not the MusicBrainz artist.



album

LastFMAlbum



The album on which the track appears. This returns the Last.fm album info,

not the MusicBrainz release.



similarTracks

LastFMTrackConnection



A list of similar tracks.



first

Int



The maximum number of tracks to retrieve.



after

String



The cursor of the edge after which more tracks will be retrieved.



topTags

LastFMTagConnection



A list of tags applied to the track by users, ordered by popularity.



first

Int



The maximum number of tags to retrieve.



after

String



The cursor of the edge after which more tags will be retrieved.



#### LastFMTrackConnection



A connection to a list of items.



Field

Argument

Type

Description



pageInfo

PageInfo!



Information to aid in pagination.



edges

[LastFMTrackEdge]



A list of edges.



nodes

[LastFMTrack]



A list of nodes in the connection (without going through the `edges` field).



totalCount

Int



A count of the total number of items in this connection, ignoring pagination.



#### LastFMTrackEdge



An edge in a connection.



Field

Argument

Type

Description



node

LastFMTrack



The item at the end of the edge.



cursor

String!



A cursor for use in pagination.



matchScore

Float



The track similarity score (0–1) as determined by [Last.fm](https://www.last.fm/),

if this connection is with another track.



#### LastFMWikiContent



Biographical or background information written about an entity on

[Last.fm](https://www.last.fm/).



Field

Argument

Type

Description



summaryHTML

String



A summary of the wiki content, which may contain HTML.



contentHTML

String



The full wiki content, which may contain HTML.



publishDate

Date



The date the content was published. The data is reformatted from the

Last.fm API’s original format into the Date scalar format.



publishTime

Time



The time the content was published. The data is reformatted from the

Last.fm API’s original format into the Time scalar format. The API offers

no indication as to which time zone the time is in.



url

URLString



The URL at which the content was published.



#### Query



:small_blue_diamond: *This type has been extended.

See the [base schema](https://github.com/exogen/graphbrainz/docs/types.md) for a description and additional fields.*



Field

Argument

Type

Description



lastFM

LastFMQuery



A query for data on [Last.fm](https://www.last.fm/) that is not connected

to any particular MusicBrainz entity. This field is provided by the

Last.fm extension.



#### Recording



:small_blue_diamond: *This type has been extended.

See the [base schema](https://github.com/exogen/graphbrainz/docs/types.md) for a description and additional fields.*



Field

Argument

Type

Description



lastFM

LastFMTrack



Data about the recording from [Last.fm](https://www.last.fm/), a good

source for measuring popularity via listener and play counts. This field

is provided by the Last.fm extension.



#### Release



:small_blue_diamond: *This type has been extended.

See the [base schema](https://github.com/exogen/graphbrainz/docs/types.md) for a description and additional fields.*



Field

Argument

Type

Description



lastFM

LastFMAlbum



Data about the release from [Last.fm](https://www.last.fm/), a good source

for measuring popularity via listener and play counts. This field is

provided by the Last.fm extension.



### Enums



#### LastFMImageSize



The image sizes that may be requested at [Last.fm](https://www.last.fm/).



Value

Description



SMALL



A maximum dimension of 34px.



MEDIUM



A maximum dimension of 64px.



LARGE



A maximum dimension of 174px.



EXTRALARGE



A maximum dimension of 300px.



MEGA



A maximum dimension of 300px.



[Last.fm]: https://www.last.fm/

[Last.fm API]: https://www.last.fm/api

[GraphBrainz]: https://github.com/exogen/graphbrainz

[demo]: https://graphbrainz-extension-lastfm.herokuapp.com/