Skip to content

exogen/graphbrainz-extension-discogs

Repository files navigation

GraphBrainz Extension: Discogs

build status coverage npm version license

Retrieve information about MusicBrainz entities from Discogs using the Discogs API. This project has no affiliation with Discogs.

The extension works by finding Discogs URLs in an entity’s URL relationships. The URL relationship must have the discogs type and point to a Discogs entity of the appropriate type: artist for artists, label for labels, master for release groups, and release for releases.

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-discogs
$ GRAPHBRAINZ_EXTENSIONS='["graphbrainz-extension-discogs"]' 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-discogs']
})

Configuration

This extension can be configured using environment variables:

  • DISCOGS_CONSUMER_KEY: The Discogs consumer key to use. This is not strictly required, but will get you more favorable rate limiting.
  • DISCOGS_CONSUMER_SECRET: The Discogs consumer secret to use. This is not strictly required, but will get you more favorable rate limiting.
  • DISCOGS_BASE_URL: The base URL at which to access the Discogs API. Defaults to https://api.discogs.com/.
  • DISCOGS_CACHE_SIZE: The number of items to keep in the cache. Defaults to GRAPHBRAINZ_CACHE_SIZE if defined, or 8192.
  • DISCOGS_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 community ratings, collection counts, and marketplace info for various releases of OK Computer (try it):

{
  search {
    releases(query: "OK Computer", first: 5) {
      nodes {
        mbid
        title
        discogs {
          year
          country
          forSaleCount
          lowestPrice
          community {
            haveCount
            wantCount
            rating {
              voteCount
              value
            }
          }
        }
      }
    }
  }
}

Schema Types

Table of Contents

Objects

Artist

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

Field Argument Type Description
discogs DiscogsArtist

Information about the artist on Discogs.

DiscogsArtist

An artist on Discogs.

Field Argument Type Description
artistID ID!

The ID of the artist on Discogs.

name String!

The name of the artist on Discogs.

nameVariations [String!]!

Commonly found variations of the artist’s name.

realName String

The artist’s real name, if the artist is a person who uses a stage name.

aliases [DiscogsArtist!]!

A list of Discogs artists that represent the same artist under a different alias.

url URLString!

The URL of the artist’s page on Discogs.

urls [URLString!]!

Links to the artist’s official pages on different web properties.

profile String

A biography or description of the artist.

images [DiscogsImage!]!

A list of images picturing the artist.

members [DiscogsArtistMember!]!

A list of members, if the artist is a group.

dataQuality String

A description of the quality and completeness of this artist’s data in the Discogs database.

DiscogsArtistCredit

A credited artist on a release, track, etc.

Field Argument Type Description
name String

The official or common name of the credited artist.

nameVariation String

The artist name as credited on this particular work (the Artist Name Variation, or ANV, in Discogs terms).

joinPhrase String

Join phrases might include words and/or punctuation to separate artist names as they appear on the release, track, etc.

roles [String!]!

A list of roles the artist had on the work in question.

tracks [String!]!

A list of tracks or track ranges (e.g. “A1 to A4”) on which the artist is credited.

artist DiscogsArtist

The artist’s entry on Discogs.

DiscogsArtistMember

A single artist who is a member of a group on Discogs.

Field Argument Type Description
active Boolean

Whether or not the member is still active in the group.

name String!

The name of the member.

artist DiscogsArtist

The member’s artist information on Discogs.

DiscogsCommunity

Community statistics regarding an item on Discogs.

Field Argument Type Description
status String

The acceptance status.

rating DiscogsRating

Information about how Discogs users have rated the item.

haveCount Int

The number of Discogs users who have the item in their collection.

wantCount Int

The number of Discogs users who want the item.

contributors [DiscogsUser!]!

The Discogs users who have contributed to the item’s data.

submitter DiscogsUser

The Discogs user who submitted the item.

DiscogsImage

A single image from Discogs.

Field Argument Type Description
url URLString!

The URL of the image file.

type DiscogsImageType!

The image type, primary or secondary.

width Int!

The image width in pixels.

height Int!

The image height in pixels.

thumbnail URLString

The URL for a 150x150 thumbnail of the image.

DiscogsLabel

A label on Discogs.

Field Argument Type Description
labelID ID!

The ID of the label on Discogs.

name String!

The name of the label.

url URLString!

The URL of the label on Discogs.

profile String

A description of the history of the label.

contactInfo String

Information on how to contact a representative of the label.

parentLabel DiscogsLabel

The parent label, if this label is a subsidiary.

subLabels [DiscogsLabel!]!

A list of labels that are subsidiaries of this label.

images [DiscogsImage!]!

A list of images associated with the label.

dataQuality String

A description of the quality and completeness of this label’s data in the Discogs database.

DiscogsMaster

Master releases group different versions of the same release (for example, releases in different formats, issued in different countries, re-releases, etc.). The equivalent of a MusicBrainz release group.

Field Argument Type Description
masterID ID!

The ID of the master on Discogs.

title String!

The title of the master.

url URLString!

The URL of the master on Discogs.

artistCredits [DiscogsArtistCredit!]!

The artists credited on the master.

genres [String!]!

The primary musical genres of the master (e.g. “Electronic”).

styles [String!]!

The primary musical styles of the master (e.g. “Techno”, “Minimal”).

forSaleCount Int

The number of listings the master currently has on the marketplace.

lowestPrice Float

The lowest price for the master currently found on the marketplace.

currency String

The three-letter currency code for which to retrieve the price. Discogs supports USD, GBP, EUR, CAD, AUD, JPY, CHF, MXN, BRL, NZD, SEK, and ZAR.

[NOT YET WORKING]

year Int

The year the master was released (most likely its “main” release).

mainRelease DiscogsRelease

The main release from the master.

images [DiscogsImage!]!

Images of the master.

videos [DiscogsVideo!]!

Music videos from the master.

dataQuality String

A description of the quality and completeness of this master’s data in the Discogs database.

DiscogsRating

An aggregated rating on Discogs.

Field Argument Type Description
voteCount Int!

The number of users who have contributed to the rating.

value Float

The average rating as determined by users.

DiscogsRelease

A release on Discogs.

Field Argument Type Description
releaseID ID!

The ID of the release on Discogs.

title String!

The title of the release.

url URLString!

The URL of the release on Discogs.

artistCredits [DiscogsArtistCredit!]!

The artists credited on the release.

extraArtistCredits [DiscogsArtistCredit!]!

An additional list of artists who contributed to the release, but are not named in the release’s artists.

genres [String!]!

The primary musical genres of the release (e.g. “Electronic”).

styles [String!]!

The primary musical styles of the release (e.g. “Techno”, “Minimal”).

forSaleCount Int

The number of listings the release currently has on the marketplace.

lowestPrice Float

The lowest price for the release currently found on the marketplace.

currency String

The three-letter currency code for which to retrieve the price. Discogs supports USD, GBP, EUR, CAD, AUD, JPY, CHF, MXN, BRL, NZD, SEK, and ZAR.

[NOT YET WORKING]

year Int

The year the release was issued.

notes String

Notes about the release.

country String

The country in which the release was issued.

master DiscogsMaster

The master release on Discogs.

thumbnail URLString

The primary thumbnail image for the release.

images [DiscogsImage!]!

Images of the release.

videos [DiscogsVideo!]!

Music videos from the release.

community DiscogsCommunity

Information about the Discogs community’s contributions to the release’s data.

dataQuality String

A description of the quality and completeness of this release’s data in the Discogs database.

DiscogsReleaseConnection

A connection to a list of Discogs releases.

Field Argument Type Description
pageInfo PageInfo!

Information to aid in pagination.

edges [DiscogsReleaseEdge!]!

A list of edges.

nodes [DiscogsRelease!]!

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.

DiscogsReleaseEdge

An edge in a Discogs release connection.

Field Argument Type Description
node DiscogsRelease!

The release at the end of the edge.

DiscogsUser

A user on Discogs.

Field Argument Type Description
username String!

The user’s username on Discogs.

DiscogsVideo

A single video linked from Discogs.

Field Argument Type Description
url URLString!

The URL of the video.

title String

The title of the video.

description String

The video description.

duration Duration

The duration of the video in milliseconds.

embed Boolean

Whether the video is embeddable.

Label

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

Field Argument Type Description
discogs DiscogsLabel

Information about the label on Discogs.

Release

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

Field Argument Type Description
discogs DiscogsRelease

Information about the release on Discogs.

ReleaseGroup

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

Field Argument Type Description
discogs DiscogsMaster

Information about the release group on Discogs.

Enums

DiscogsImageType

The type of image.

Value Description
PRIMARY

The primary image representing the item.

SECONDARY

A secondary image representing the item.