Connecting to Discogs

Overview

Discogs is a website and crowdsourced database of information about audio recordings, including commercial releases, promotional releases, and bootleg or off-label releases.

More Information on Discogs

Prerequisites

Step 1: Include required gem for processing linked data

You will need to add the ruby-rdf/linkeddata gem that processes a large number of linked data serializations. The Discogs API returns JSON, not linked data. However, the Discogs Authority provides the option of converting the Discogs data to JSON-LD, and this process requires serialization.

gem 'linkeddata'

Step 2: Signup with Discogs

You need to register for a Discogs account, which is explained on the Discogs authentication page. Create an application to receive a Consumer Key and Secret. Once you have those, you can run queries like this:

https://api.discogs.com/database/search?q=sinatra&type=release&key=CONSUMER_KEY&secret=CONSUMER_SECRET

You should see about 10 results for this URL.

Step 3: Generate Discogs configuration

Run this command to install the configuration files:

rails generate qa:discogs

Step 4: Register your Discogs account name in QA

Put the following statements in an initializer and restart the rails server.

Qa::Authorities::Discogs.discogs_key = 'CONSUMER_KEY'
Qa::Authorities::Discogs.discogs_secret = 'CONSUMER_SECRET'

Accessing via QA

Authority:	discogs

Subauthorities:

• master
• release
• all

NOTE: The "all"" subauthority returns both masters and releases.

---

Example search queries

Example search:

/qa/search/discogs/release?q=sinatra+the+modernaires

Result:

  [{
	"uri": "https://www.discogs.com/Frank-Sinatra-And-The-Modernaires-Sorry-Why-Remind-Me/release/4212473",
	"id": "4212473",
	"label": "Frank Sinatra And The Modernaires - Sorry / Why Remind Me",
	"context": [{
		"property": "Image URL",
		"values": ["https://img.discogs.com/1358693671-5430.jpeg.jpg"]
	}, {
		"property": "Year",
		"values": ["1950"]
	}, {
		"property": "Record Labels",
		"values": ["Columbia"]
	}, {
		"property": "Formats",
		"values": ["Shellac", "10\"", "78 RPM"]
	}, {
		"property": "Type",
		"values": ["release"]
	}]
  }]

Use the context to provide additional information about each item in the results display. Also, the Type value can be used in the JavaScript "select" event to set the subauthority for the term fetch.

NOTE: The qa request is converted to the following Discogs request. This is for information only. You do not need to know this to use QA.

https://api.discogs.com/database/search?q=sinatra+the+modernaires&type=release&key=dummy_key&secret=dummy_secret

---

Examples term fetch request

When the format is JSON, Discogs data is returned without being altered. When the format is JSON-LD, the translation module converts the Discogs data into linked data relationships and maps Discogs terms to their corresponding BIBFRAME properties.

Example fetch, JSON format:

/qa/show/discogs/release/3380671

Result:

{
  "status": "Accepted",
  "labels": [
    {
      "name": "Blue Note"
    }
  ],
  "year": 1962,
  "artists": [
    {
      "name": "Dexter Gordon"
    }
  ],
  "id": 3380671,
  "genres": [
    "Jazz"
  ],
  "title": "A Swingin' Affair",
  "styles": [
    "Hard Bop"
  ],
  "formats": [
    {
      "qty": "1",
      "descriptions": [
        "LP",
        "Album",
        "Mono"
      ],
      "name": "Vinyl"
    }
  ],
  etc.
}

NOTE: The qa request is converted to the following Discogs request. This is for information only. You do not need to know this to use QA.

https://api.discogs.com/releases/3380671

Example fetch, JSON-LD format:

/qa/show/discogs/master/950011?format=jsonld

Result:

{
  "@context": {
    "bf2": "http://id.loc.gov/ontologies/bibframe/",
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  },
  "@graph": [
    {
      "@id": "Work1",
      "bf2:hasPart": [
        {
          "@id": "Work3"
        },
        {
          "@id": "Work2"
        }
      ],
      "bf2:genreForm": {
        "@id": "http://id.loc.gov/authorities/genreForms/gf2014026879"
      },
      "bf2:contribution": {
        "@id": "Work1PrimaryContribution1"
      },
      "bf2:title": {
        "@id": "Work1Title"
      },
      "bf2:provisionActivity": {
        "@id": "Work1ProvisionActivityDate"
      },
      "@type": [
        "bf2:Work",
        "bf2:Audio"
      ]
    },
    {
      "@id": "http://id.loc.gov/authorities/genreForms/gf2014026879",
      "rdfs:label": "Jazz",
      "@type": "bf2:GenreForm"
    },
    {
      "@id": "Work1PrimaryContribution1",
      "bf2:agent": {
        "@id": "Work1PrimaryContribution1Agent"
      },
      "@type": "http://id.loc.gov/ontologies/bflc/PrimaryContribution"
    },
    {
      "@id": "Work1Title",
      "bf2:mainTitle": "Blue Moon / You Go To My Head"
    },
    {
      "@id": "Work1PrimaryContribution1Agent",
      "rdfs:label": "Billie Holiday And Her Orchestra",
      "@type": "bf2:Agent"
    },
  etc.
}

NOTE: The qa request is converted to the following Discogs request. This is for information only. You do not need to know this to use QA.

https://api.discogs.com/masters/950011

---

Example list all terms

Not supported

---

JavaScript example search and show

In this example the search is using the "all" subauthority, which returns both masters and releases. On the select event, the subauthority gets set to the type that the user selects.

$('input#discogs').autocomplete({
  minLength: 3,
  source: function(request, response) {
   	$.ajax({
      url: '/qa/search/discogs/all', 
	  type: 'GET',
      dataType: 'json',
	  data: {
	    q: request.term,
	  },
      complete: function(xhr, status) {
        var results = $.parseJSON(xhr.responseText);
		if ( results.length > 0 ) {
          response(results);
        }
      } 
   	});
  },
  select: function(event, ui) {
    $.ajax({
      url: '/qa/show/discogs/' + ui.item.id, 
 		type: 'GET',
  	data: {
  	  format: 'jsonld',
  	  subauthority: ui.item.context.Type[0]
  	},
      dataType: 'json',
      complete: function(xhr, status) {
        var results = $.parseJSON(xhr.responseText);
  	  [ your function for rendering the results ] 
     	} 
    });
  }
});

---

Documentation

Discogs documents their API at... https://www.discogs.com/developers/