GraphBrainz Extension: Spotify

Retrieve information about MusicBrainz entities from Spotify using GraphQL, calling the Spotify Web API under the hood. This project has no affiliation with Spotify.

The extension works by finding Spotify URLs in an entity’s URL relationships. The URL relationship must have the streaming music type and point to a Spotify entity of the appropriate type: artist for artists, album for releases, and track for recordings.

Try out the live demo! 💡 Use the “Docs” sidebar or the documentation below to help construct your query.

Installation

To use this extension, install GraphBrainz, then:

$ npm install graphbrainz-extension-spotify
$ GRAPHBRAINZ_EXTENSIONS='["graphbrainz-extension-spotify"]' graphbrainz

Or, if you are using the middleware directly:

import graphbrainz from 'graphbrainz'
 
const middleware = graphbrainz({
  // Don't forget to add the other extensions you use, too.
  extensions: ['graphbrainz-extension-spotify']
})

Configuration

This extension can be configured using environment variables:

• SPOTIFY_CLIENT_ID: The Spotify client ID to use. This is required.
• SPOTIFY_CLIENT_SECRET: The Spotify client secret to use. This is required.
• SPOTIFY_BASE_URL: The base URL at which to access the Spotify API. Defaults to https://api.spotify.com/v1/.
• SPOTIFY_CACHE_SIZE: The number of items to keep in the cache. Defaults to GRAPHBRAINZ_CACHE_SIZE if defined, or 8192.
• SPOTIFY_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

Get the audio features and related artists for a track (try it):

{
  lookup {
    recording(mbid: "6c128cd9-94da-44fe-b74f-b68079fb1606") {
      spotify {
        title
        previewURL
        audioFeatures {
          acousticness
          danceability
          duration
          energy
          instrumentalness
          keyName
          liveness
          loudness
          mode
          speechiness
          tempo
          timeSignature
          valence
        }
        artists {
          name
          relatedArtists {
            name
            href
          }
        }
      }
    }
  }
}

Schema Types

Table of Contents

• Objects
  • Artist
  • Query
  • Recording
  • Release
  • SpotifyAlbum
  • SpotifyArtist
  • SpotifyAudioFeatures
  • SpotifyCopyright
  • SpotifyExternalID
  • SpotifyExternalURL
  • SpotifyImage
  • SpotifyQuery
  • SpotifyRecommendations
  • SpotifyTrack
• Enums
  • SpotifyCopyrightType
  • SpotifyMatchStrategy
  • SpotifyTrackMode

Objects

Artist

🔹 This type has been extended. See the base schema for a description and additional fields.

Field	Argument	Type	Description
spotify		SpotifyArtist	The artist’s entry on Spotify.

Query

🔹 This type has been extended. See the base schema for a description and additional fields.

Field	Argument	Type	Description
spotify		SpotifyQuery!

Recording

🔹 This type has been extended. See the base schema for a description and additional fields.

Field	Argument	Type	Description
spotify		SpotifyTrack	The recording’s entry on Spotify.
strategy		[SpotifyMatchStrategy!]	The strategies to use to match the recording with a Spotify track, in preferential order.

Release

🔹 This type has been extended. See the base schema for a description and additional fields.

Field	Argument	Type	Description
spotify		SpotifyAlbum	The release’s entry on Spotify.
strategy		[SpotifyMatchStrategy!]	The strategies to use to match the release with a Spotify album, in preferential order.

SpotifyAlbum

An album from Spotify.

Field	Argument	Type	Description
albumID		ID!	The Spotify ID for the album.
uri		String!	The Spotify URI for the album.
href		URLString!	A link to the Web API endpoint providing full details of the album.
title		String	The name of the album. In case of an album takedown, the value may be empty.
albumType		ReleaseGroupType!	The type of the album, e.g. “Album”, “Single”, “Compilation”.
artists		[SpotifyArtist!]!	The artists of the album.
availableMarkets		[String!]!	The markets in which the album is available: ISO 3166-1 alpha-2 country codes. Note that an album is considered available in a market when at least 1 of its tracks is available in that market.
copyrights		[SpotifyCopyright!]!	The copyright statements of the album.
externalIDs		[SpotifyExternalID!]!	Known external IDs for the album.
externalURLs		[SpotifyExternalURL!]!	Known external URLs for this album.
genres		[String!]!	A list of the genres used to classify the album. For example: “Prog Rock”, “Post-Grunge”. (If not yet classified, the array is empty.)
images		[SpotifyImage!]!	The cover art for the album in various sizes, widest first.
label		String	The label for the album.
popularity		Int!	The popularity of the album. The value will be between 0 and 100, with 100 being the most popular. The popularity is calculated from the popularity of the album’s individual tracks.
releaseDate		Date	The date the album was first released, for example “1981-12-15”. Depending on the precision, the month or day might be missing.

SpotifyArtist

An artist from Spotify.

Field	Argument	Type	Description
artistID		ID!	The Spotify ID for the artist.
uri		String!	The Spotify URI for the artist.
href		URLString!	A link to the Web API endpoint providing full details of the artist.
name		String!	The name of the artist.
externalURLs		[SpotifyExternalURL!]!	Known external URLs for this artist.
genres		[String!]!	A list of the genres the artist is associated with. For example: “Prog Rock”, “Post-Grunge”. (If not yet classified, the array is empty.)
popularity		Int!	The popularity of the artist. The value will be between 0 and 100, with 100 being the most popular. The artist’s popularity is calculated from the popularity of all the artist’s tracks.
images		[SpotifyImage!]!	Images of the artist in various sizes, widest first.
topTracks		[SpotifyTrack!]!	Spotify catalog information about an artist’s top tracks by country.
market		String!	An ISO 3166-1 alpha-2 country code.
relatedArtists		[SpotifyArtist!]!	Spotify catalog information about artists similar to a given artist. Similarity is based on analysis of the Spotify community’s listening history.

SpotifyAudioFeatures

The audio features of a track from Spotify.

Field	Argument	Type	Description
acousticness		Float!	A confidence measure from 0.0 to 1.0 of whether the track is acoustic. 1.0 represents high confidence the track is acoustic.
danceability		Float!	Danceability describes how suitable a track is for dancing based on a combination of musical elements including tempo, rhythm stability, beat strength, and overall regularity. A value of 0.0 is least danceable and 1.0 is most danceable.
duration		Duration!	The duration of the track in milliseconds.
energy		Float!	Energy is a measure from 0.0 to 1.0 and represents a perceptual measure of intensity and activity. Typically, energetic tracks feel fast, loud, and noisy. For example, death metal has high energy, while a Bach prelude scores low on the scale. Perceptual features contributing to this attribute include dynamic range, perceived loudness, timbre, onset rate, and general entropy.
instrumentalness		Float!	Predicts whether a track contains no vocals. “Ooh” and “aah” sounds are treated as instrumental in this context. Rap or spoken word tracks are clearly “vocal”. The closer the instrumentalness value is to 1.0, the greater likelihood the track contains no vocal content. Values above 0.5 are intended to represent instrumental tracks, but confidence is higher as the value approaches 1.0.
key		Int!	The key the track is in. Integers map to pitches using standard Pitch Class notation, e.g. 0 = C, 1 = C♯/D♭, 2 = D, and so on. See the keyName field if you’d prefer the note as a string.
keyName		String!	The key translated from an integer to a name like “C”. (Only one name will be returned, so enharmonic notes like like C♯/D♭ will just return “C♯”.)
liveness		Float!	Detects the presence of an audience in the recording. Higher liveness values represent an increased probability that the track was performed live. A value above 0.8 provides strong likelihood that the track is live.
loudness		Float!	The overall loudness of a track in decibels (dB). Loudness values are averaged across the entire track and are useful for comparing relative loudness of tracks. Loudness is the quality of a sound that is the primary psychological correlate of physical strength (amplitude). Values typical range between -60 and 0 db.
mode		SpotifyTrackMode!	Mode indicates the modality (major or minor) of a track, the type of scale from which its melodic content is derived. Major is represented by 1 and minor is 0.
speechiness		Float!	Speechiness detects the presence of spoken words in a track. The more exclusively speech-like the recording (e.g. talk show, audio book, poetry), the closer to 1.0 the attribute value. Values above 0.66 describe tracks that are probably made entirely of spoken words. Values between 0.33 and 0.66 describe tracks that may contain both music and speech, either in sections or layered, including such cases as rap music. Values below 0.33 most likely represent music and other non-speech-like tracks.
tempo		Float!	The overall estimated tempo of a track in beats per minute (BPM). In musical terminology, tempo is the speed or pace of a given piece and derives directly from the average beat duration.
timeSignature		Float!	An estimated overall time signature of a track. The time signature (meter) is a notational convention to specify how many beats are in each bar (or measure).
valence		Float!	A measure from 0.0 to 1.0 describing the musical positiveness conveyed by a track. Tracks with high valence sound more positive (e.g. happy, cheerful, euphoric), while tracks with low valence sound more negative (e.g. sad, depressed, angry).

SpotifyCopyright

A copyright statement for an album from Spotify.

Field	Argument	Type	Description
text		String!	The copyright text.
type		SpotifyCopyrightType!	Whether the copyright is for the work itself or the sound recording (performance).

SpotifyExternalID

A value for identifying an entity with some third party.

Field	Argument	Type	Description
type		String!	The identifier type, for example “isrc”, “ean”, “upc”.
id		String!	The identifier value.

SpotifyExternalURL

A URL for linking to an entity with some third party.

Field	Argument	Type	Description
type		String!	The type of the URL, for example “spotify”.
url		URLString!	An external, public URL to the object.

SpotifyImage

A single image from Spotify.

Field	Argument	Type	Description
url		URLString!	The source URL of the image.
width		Int	The image width in pixels, if known.
height		Int	The image height in pixels, if known.

SpotifyQuery

Field	Argument	Type	Description
recommendations		SpotifyRecommendations!	Track recommendations based on seed entities and various parameters.
seedArtists		[ID!]	A list of Spotify IDs for seed artists. Up to 5 seed values may be provided in any combination of seedArtists, seedTracks, and seedGenres.
seedGenres		[ID!]	A comma separated list of any genres in the set of available genre seeds. Up to 5 seed values may be provided in any combination of seedArtists, seedTracks, and seedGenres.
seedTracks		[ID!]	A list of Spotify IDs for seed tracks. Up to 5 seed values may be provided in any combination of seedArtists, seedTracks, and seedGenres.
limit		Int	The target size of the list of recommended tracks. For seeds with unusually small pools or when highly restrictive filtering is applied, it may be impossible to generate the requested number of recommended tracks. Debugging information for such cases is available in the response. Default: 20. Minimum: 1. Maximum: 100.

SpotifyRecommendations

Field	Argument	Type	Description
tracks		[SpotifyTrack!]!

SpotifyTrack

A track from Spotify.

Field	Argument	Type	Description
trackID		ID!	The Spotify ID for the track.
uri		String!	The Spotify URI for the track.
href		URLString!	A link to the Web API endpoint providing full details of the track.
title		String!	The name of the track.
audioFeatures		SpotifyAudioFeatures	The audio features of the track.
album		SpotifyAlbum	The album on which the track appears.
artists		[SpotifyArtist!]!	The artists who performed the track.
availableMarkets		[String!]!	A list of the countries in which the track can be played, identified by their ISO 3166-1 alpha-2 code.
discNumber		Int!	The disc number (usually 1 unless the album consists of more than one disc).
duration		Duration!	The track length in milliseconds.
explicit		Boolean	Whether or not the track has explicit lyrics, if known.
externalIDs		[SpotifyExternalID!]!	Known external IDs for the track.
externalURLs		[SpotifyExternalURL!]!	Known external URLs for the track.
popularity		Int!	The popularity of the track. The value will be between 0 and 100, with 100 being the most popular. The popularity is calculated by algorithm and is based, in the most part, on the total number of plays the track has had and how recent those plays are. Generally speaking, songs that are being played a lot now will have a higher popularity than songs that were played a lot in the past. Duplicate tracks (e.g. the same track from a single and an album) are rated independently. Artist and album popularity is derived mathematically from track popularity. Note that the popularity value may lag actual popularity by a few days: the value is not updated in real time.
previewURL		URLString	A link to a 30 second preview (MP3 format) of the track, if available.
trackNumber		Int!	The number of the track. If an album has several discs, the track number is the number on the specified disc.
musicBrainz		Recording	A MusicBrainz recording that corresponds to the track.
strategy		[SpotifyMatchStrategy!]	The strategies to use to match the track with a MusicBrainz recording, in preferential order.

Enums

SpotifyCopyrightType

The type of copyright.

Value	Description
COPYRIGHT	The copyright.
PERFORMANCE	The sound recording (performance) copyright.

SpotifyMatchStrategy

Strategies for matching MusicBrainz entities to Spotify entities.

Value	Description
URL	The entity will be matched by finding an explicit URL relationship that links to Spotify.
EXTERNALID	The entity will be matched by searching for Spotify entities by some external ID that is known to both MusicBrainz and Spotify, like an ISRC or UPC barcode. Since this can result in multiple Spotify matches, the most popular will be preferred (if possible), or the first.

SpotifyTrackMode

The potential values for modality (major or minor) of a track.

Value	Description
MAJOR	The major scale.
MINOR	The minor scale.