Cover Art Archive/API

From MusicBrainz Wiki
< Cover Art Archive
Revision as of 12:45, 22 March 2012 by Jokipii (talk | contribs) (Added in Category:Development)
Jump to navigationJump to search

Any requests to fetch cover art must go through the coverartarchive.org service. There are 3 classes of end points, text surrounded in braces indicates a variable.

/release/{mbid}/

Summary

Fetches a JSON listing of available cover art for a MusicBrainz release.

Accepted Methods

- GET

- HEAD

Responses

- 200 if there is a release with this MBID.

- 400 if {mbid} cannot be parsed as a valid UUID.

- 404 if there is no release with this MBID.

- 405 if the request method is not one of GET or HEAD.

- 406 if the server is unable to generate a response suitable to the Accept header.

- 503 if the user has exceeded their rate limit.

Example

   > GET /release/99b09d02-9cc9-3fed-8431-f162165a9371 HTTP/1.1
   > Host: coverartarchive.org
   > Accept: application/json
   < HTTP/1.0 200 OK
   < Status: 200
   {
     "release": {
       "name": "We Hear You",
       "artist_credit": "Luke Vibert"
     },
     "artwork": [
       {
         "approved": true,
         "id": "135741621",
         "front": true
       }
     ]
   }


/release/{mbid}/front

Summary

Fetches the image that is most suitable to be called the "front" of a release. This is intentionally vague, and users will help curate this data into something that is meaningful, but here you'll find the artwork that users would most likely expect to see in:

  • Digital shops when searching for the release
  • Their portable media player
  • The folder icon in their file browser, if supported
  • What they would expect to find if they were looking for this release in a shop.

Accepted Methods

- GET

- HEAD

Responses

- 307 if the community have decided upon a "front" image for this release.

- 400 if {mbid} cannot be parsed as a valid UUID.

- 404 if there is either no release with this MBID, or the community have not chosen an image to represent the front of a release.

- 405 if the request method is not GET or HEAD.

- 503 if the user has exceeded their rate limit.

Example

   > GET /release/99b09d02-9cc9-3fed-8431-f162165a9371/front HTTP/1.1
   > Host: coverartarchive.org
   < HTTP/1.1 307 Temporary Redirect
   < Status: 307
   < Location: http://archive.org/download/mbid-99b09d02-9cc9-3fed-8431-f162165a9371/mbid-99b09d02-9cc9-3fed-8431-f162165a9371-135741621.jpg


/release/{mbid}/back

Summary

Fetches the image that is most suitable to be called the "back" of a release. This is intentionally vague, and users will help curate this data into something that is meaningful, but here you'll usually find artwork that includes:

  • A tracklisting, barcode, and label
  • What users would expect to find on the back cover if they were looking for this release in a shop.

Accepted Methods

- GET

- HEAD

Responses

- 307 if the community have decided upon a "back" image for this release.

- 400 if {mbid} cannot be parsed as a valid UUID.

- 404 if there is either no release with this MBID, or the community have not chosen an image to represent the back of a release.

- 405 if the request method is not GET or HEAD.

- 503 if the user has exceeded their rate limit.

Example

   > GET /release/99b09d02-9cc9-3fed-8431-f162165a9371/back HTTP/1.1
   > Host: coverartarchive.org
   < HTTP/1.1 307 Temporary Redirect
   < Status: 307
   < Location: http://archive.org/download/mbid-99b09d02-9cc9-3fed-8431-f162165a9371/mbid-99b09d02-9cc9-3fed-8431-f162165a9371-135822686.jpg


/release/{mbid}/{id}

Summary

Fetches a specific piece of artwork. The possible {id} values can be found by parsing the response of a /release/{mbid} request.

Accepted methods

- GET

- HEAD

Responses

- 307 redirect to a binary image.

- 404 if a release with this MBID cannot be found.

- 405 if the request method is not GET or HEAD.

- 503 if the user has exceeded their rate limit.

Example

   > GET /release/foo/135741621.jpg HTTP/1.1
   > Host: coverartarchive.org
   < HTTP/1.1 307 Temporary Redirect
   < Status: 307
   < Location: http://archive.org/download/mbid-99b09d02-9cc9-3fed-8431-f162165a9371/mbid-99b09d02-9cc9-3fed-8431-f162165a9371-135741621.jpg


/release/{mbid}/{id}-(250|500)

Summary

Fetches a thumbnail for a specific piece of artwork. The possible {id} values can be found by parsing the response of a /release/{mbid} request. The current supported thumbnail sizes are 250px and 500px.

Accepted methods

- GET

- HEAD

Responses

- 307 redirect to a binary image. This redirected request may resolve to a 404 if the thumbnail does not exist.

- 404 if a release with this MBID cannot be found.

- 405 if the request method is not GET or HEAD.

- 503 if the user has exceeded their rate limit.

Example

   > GET /release/99b09d02-9cc9-3fed-8431-f162165a9371/135741621-250.jpg HTTP/1.1
   > Host: coverartarchive.org
   < HTTP/1.1 307 Temporary Redirect
   < Status: 307
   < Location: http://archive.org/download/mbid-99b09d02-9cc9-3fed-8431-f162165a9371/mbid-99b09d02-9cc9-3fed-8431-f162165a9371-135741621-250.jpg


OPTIONS support

All end points at the coverartarchive.org support the HTTP OPTIONS method, to determine which request methods are valid for each resource. On an OPTIONS request, the server will do no processing, other than returning an empty response with the 'Allow:' header field set to the support methods for that resource. For supported methods, consult the specification of each individual resource.

Cover Art Archive Metadata

The Cover Art Archive provides a collection of metadata with each release, which allows users to determine what cover art can be used for. The metadata will be stored and served as application/json. The metadata consists of a list of entries, where each entry contains:

- _image_: the full coverartarchive.org url to the original image

- _thumbnails_: { small: “http://coverartarchive.org/...-250.jpg”, large: “http://coverartarchive.org/...-500.jpg” }

- _types_: list of one or more types for the image (see the list).

- _front_: boolean

- _back_: boolean

- _comment_: a free text comment

- _appproved_: whether the image was approved by the musicbrainz edit system

- _edit_: full url to the edit on musicbrainz (e.g. musicbrainz.org/edit/123)


The metadata also contains a link to the MusicBrainz release, under the _release_ field.

JSON Output Example

 {
  	"images" : [
  		{
  			"types" : [ "Other" ],
  			"front" : true,
  			"back" : false,
  			"comment" : "",
  			"image" : "http://coverartarchive.org/...jpg",
  			"thumbnails" : {
  				"small" : "http://coverartarchive.org/...-250.jpg",
  				"large" : "http://coverartarchive.org/...-500.jpg"
  			},
  			"approved" : true,
  			"edit" : "http://musicbrainz.org/edit/123"
  		},
  		{
  			"types" : [ "Other" ],
  			"front" : false,
  			"back" : false,
  			"comment" : "autographed by ModBot",
  			"image" : "http://coverartarchive.org/...jpg",
  			"thumbnails" : {
  				"small" : "http://coverartarchive.org/...-250.jpg",
  				"large" : "http://coverartarchive.org/...-500.jpg"
  			},
  			"approved" : true,
  			"edit" : "http://musicbrainz.org/edit/123"
  		}
  	],
  	"release" : "http://musicbrainz.org/release/2ba4396d-c0be-4a56-b4ea-0438306eb3be"
  }

File naming

Files are named using integers derived from the current high resolution system time, for example via the `Time::HiRes::time` function in Perl. The exact formula to create a new file name is:

   int((time() - 1327528905) * 100)

This filename is allocated by MusicBrainz at the time of upload, and will never change.