Querying releases

GET /20220401/release
POST /20220401/release

Searches for releases. Queries to /release must be either a name query, an Acoustid fingerprint query, a CD TOC query or a MusicBrainz Disc ID query.

Queries can be sent as a GET or POST request. In general, production use of OneMusicAPI should use POST for searches, because query URLs can otherwise get too long.

Mandatory parameters for all queries

All queries must contain the following:

user_key: Your API key.

Result schema

Result release objects follow this schema:

`Release`

Field	Type	Description
title	String (optional)	The title of the release. E.g. Dark Side of the Moon
subtitle	String (optional)	A subtitle for the release. E.g. 30th Anniversary Edition
artist	String (optional)	The artist considered the release artist. E.g. Pink Floyd
year	String (optional)	The year the release was issued.
country	String (optional)	The country or jurisdiction the release was issued within.
barcode	String (optional)	The barcode issued with the release.
genres	Array of string (optional)	All genres for this release.
compilation	true \| false (optional)	Whether this is known to be a compilation or not.
media	Array of `Medium`	All media that make up this release. For example, this could hold multiple CDs in a multi-disc release.
images	Array of `Image` (optional)	Images for this release, typically the front cover art.
uris	Array of string (optional)	URIs relating to this release.
types	Array of string (optional)	What type of release is it? E.g. a live recording, a bootleg, and official release...
label	`ReleaseLabel` (optional)	The record label that made this release.
score	Number	How confident, from 0 to 1, that OneMusicAPI has found the correct release.

`Medium`

Field	Type	Description
totalDiscs	String (optional)	The total number of mediums in the containing parent release.
position	String (optional)	The position of this medium in the release. For example, for the first CD in a multi CD set, this would be 1
format	String (optional)	The format of the medium, e.g. Vinyl, CD, MP3 etc.
tracks	Array of `Track`	The tracks contained in this medium.

`Track`

Field	Type	Description
title	String (optional)	The title of the track.
number	String (optional)	The position of the track in the medium. E.g. for the second track when playing the medium consecutively, this would be 2
duration	Number (optional)	The duration of the track in milliseconds.
artists	Array of string (optional)	Artists involved in the performance of this track.
composers	Array of string (optional)	Artists involved in the writing of this track.
isrcs	Array of string (optional)	International Standard Recording Codes (ISRCs) for the track.

`Image`

Field	Type	Description
url	String	The URL which can be re-queried to download the image.
width	String	The width of the image in pixels.
height	String	The height of the image in pixels.
score	String	The score of the quality of the image, from 0-5. 5 is highest quality. Clients should experiment to choose an appropriate value.

`ReleaseLabel`

Field	Type	Description
name	String	The name of the record label.
cat	String	The cat number for the release.

Name query

A name based query must include:

Mandatory parameters

title: The title of the release.
artist: The name of the artist for the release.

Optional parameters

track.[m.]n.name: Specify the name for a track, where 'm' is the optional medium number and where 'n' is the track number. Useful for getting better quality and more accurate results when querying with just album and artist names. These positions will be returned in the results if inc=trackMatch is also used.
format: Returns only releases which have at least one component with the specified format. For example, to return only vinyl releases, specify format=vinyl

Examples

/20220401/release?user_key=myUserKey&inc=images&title=Thriller&artist=Michael%20Jackson

Retrieves the images for Thriller by Michael Jackson.

/20220401/release?user_key=myUserKey&inc=images&title=Smooth+Criminal&artist=Michael%20Jackson&inc=images&track.1.name%3DSmooth%0ACriminal%20(extended%20dance%20mix)%26track.2.name%3DSmooth%20Criminal%20(extended%20dance%20mix%20radio%20edit)%26track.3.name%3DSmooth%20Criminal%20%0A(%22Annie%22%20mix)%26track.4.name%3DSmooth%20Criminal%20(dance%20mix%20-%20dub%20version)%26track.5.name%3DSmooth%20Criminal%20(a%20cappella)%20

Retrieves the images for the Japanese version of the Smooth Criminal single by Michael Jackson.

Acoustid fingerprint query

OneMusicAPI accepts Acoustid fingerprints in queries.

Mandatory parameters

track.[m.]n.duration: The duration of a track in seconds, where 'm' is the optional medium number and 'n' is an identifier denoting the track number. If 'n' is an integer, it is used to compare to track positions in results to refine for accuracy. Otherwise it is just a label which will be returned if inc=trackMatch is also used.
track.[m.]n.fingerprint: The Acoustid fingerprint for a track, where 'm' is the optional medium number and 'n' is an identifier denoting the track number. If 'n' is an integer, it is used to compare to track positions in results to refine for accuracy. Otherwise it is just a label which will be returned if inc=trackMatch is also used. Use the Acoustid 'fp_calc' tool to generate fingerprints.

Optional parameters

These parameters help OneMusicAPI provide a more accurate score for each matched release. They can be useful because many releases (particularly classical releases) have identical or similar track listings.

title: The title of the release.
artist: The name of the artist for the release.
track.[m.]n.name: Specify the name for a track, where 'm' is the optional medium number and where 'n' is the track number.
format: Returns only releases which have at least one component with the specified format. For example, to return only vinyl releases, specify format=vinyl

Examples

/20220401/release?user_key=myUserKey&inc=images&track.1.duration=255&track.1.fingerprint=AQABz00mRVOLmkqD[...]

Retrieves the images for the release with the specified fingerprint. The fingerprint itself if too long to be replicated here. Such queries should always be sent as a POST.

CD TOC queries

CD Table Of Contents queries can be sent to OneMusicAPI.

Mandatory parameters

track.[m.]n.offset: The offset of a track on a CD's TOC, where 'm' is the optional medium number and where 'n' is an integer denoting the track number.
track.leadout.offset: The offset of the leadout track in a CD's TOC.

MusicBrainz Disc ID queries

MusicBrainz Disc ID queries can be sent to OneMusicAPI.

Mandatory parameters

musicBrainzDiscId: Specify the MusicBrainz Disc ID to use directly in querying MusicBrainz.

Discogs ID queries

A Discogs release ID can be used to query OneMusicAPI, which will return aggregated information for that release from Discogs and all other aggregated databases to broaden the quantity of data retrievable.

Mandatory parameters

discogsId: Specify the Discogs ID which represents the release being queried.

Barcode query

Queries for releases given its barcode.

Mandatory parameters

barcode: The barcode for the release.

Optional parameters

format: Returns only releases which have at least one component with the specified format. For example, to return only vinyl releases, specify format=vinyl

Optional parameters for all queries

In addition, all queries can be further constrained with the following parameters:

inc

Additional data to return. Basic metadata is always returned, but if inc is set then the following additional items may be retrieved:

images: Return images associated with this release.
trackMatch: For track name and Acoustid fingerprint queries, return the input track.[m.]n parameter that matched each track on a release.
trackComposers: Lists composers for each individual track. The 'composer' is the writer of the music and so is relevant to non-classical recordings.
label: Include information about the record label the release was released on and the catalog number it was issued with.
sourceUri: Returns an identifier URI for the source of the data.
displayUri: Includes a display URI for the source of the data, suitable for showing to clients.
duration: Include the track durations for each track in the release.
barcode: Includes the barcode for the release.
isrc: Include the ISRCs for each track in the release.

If the requested data is not available, the remaining release information is still returned.

mustInc

Additional data that must be returned. Similarly to inc, if this parameter is set then the following additional items may be retrieved:

images: Return images associated with this release.

If the requested data is not available for a particular release, the remaining information for that release is not returned.

minCertainty

A number between 0 and 1, relating to the minimum certainty onemusicapi.com must have of the information being correct for this album. The default is 1.

maxResultCount

Number of results to return. The default is 1.

minImageWidth

An integer specifying the minimum width of any retrieved image.

minImageHeight

An integer specifying the minimum height of any retrieved image.

maxImageWidth

An integer specifying the maximum width of any retrieved image.

maxImageHeight

An integer specifying the maximum height of any retrieved image.

minImageScore

An integer between 1 and 5 inclusive specifying the required quality and/or type of image. '5' is used for high quality front covers only.

Examples

/20220401/release?user_key=myUserKey&inc=images&title=Thriller&artist=Michael%20Jackson&minCertainty=0&maxResultCount=10

Retrieves up to 10 images for Thriller by Michael Jackson of low certainty.

/20220401/release?user_key=myUserKey&inc=images&title=Thriller&artist=Michael%20Jackson&minImageWidth=500&minImageHeight=500

Retrieves images for Thriller by Michael Jackson which is at least 500x500 pixels.

Response

Here's an example response:

[
  {
    "title": "13",
    "artist": "Blur",
    "year": "1999",
    "country": "Australasia",
    "genres": [
      "Rock"
    ],
    "media": [
      {
        "totalDiscs": "1",
        "position": "1",
        "format": "CD",
        "tracks": [
          {
            "title": "Tender",
            "number": "1",
            "artists": [
              
            ]
          },
          {
            "title": "Caramel",
            "number": "10",
            "artists": [
              
            ]
          },
          {
            "title": "Trimm Trabb",
            "number": "11",
            "artists": [
              
            ]
          },
          {
            "title": "No Distance Left To Run",
            "number": "12",
            "artists": [
              
            ]
          },
          {
            "title": "Optigan 1",
            "number": "13",
            "artists": [
              
            ]
          },
          {
            "title": "Bugman",
            "number": "2",
            "artists": [
              
            ]
          },
          {
            "title": "Coffee & TV",
            "number": "3",
            "artists": [
              
            ]
          },
          {
            "title": "Swamp Song",
            "number": "4",
            "artists": [
              
            ]
          },
          {
            "title": "1992",
            "number": "5",
            "artists": [
              
            ]
          },
          {
            "title": "B.L.U.R.E.M.I.",
            "number": "6",
            "artists": [
              
            ]
          },
          {
            "title": "Battle",
            "number": "7",
            "artists": [
              
            ]
          },
          {
            "title": "Mellow Song",
            "number": "8",
            "artists": [
              
            ]
          },
          {
            "title": "Trailerpark",
            "number": "9",
            "artists": [
              
            ]
          }
        ]
      }
    ],
    "images": [
      {
        "url": "http://api.onemusicapi.com/20220401/images/discogs/1806152/1244532179.jpeg",
        "width": "600",
        "height": "593"
      }
    ],
    "uris": [
      "https://www.discogs.com/release/1806152"
    ],
    "types": [
      "Album"
    ],
    "score": 1
  },
  {
    "title": "13",
    "artist": "Blur",
    "year": "1999",
    "country": "CA",
    "genres": [
      "Rock"
    ],
    "media": [
      {
        "totalDiscs": "1",
        "position": "1",
        "format": "CD",
        "tracks": [
          {
            "title": "Tender",
            "number": "1",
            "artists": [
              
            ]
          },
          {
            "title": "Caramel",
            "number": "10",
            "artists": [
              
            ]
          },
          {
            "title": "Trimm Trabb",
            "number": "11",
            "artists": [
              
            ]
          },
          {
            "title": "No Distance Left To Run",
            "number": "12",
            "artists": [
              
            ]
          },
          {
            "title": "Optigan 1",
            "number": "13",
            "artists": [
              
            ]
          },
          {
            "title": "Bugman",
            "number": "2",
            "artists": [
              
            ]
          },
          {
            "title": "Coffee & TV",
            "number": "3",
            "artists": [
              
            ]
          },
          {
            "title": "Swamp Song",
            "number": "4",
            "artists": [
              
            ]
          },
          {
            "title": "1992",
            "number": "5",
            "artists": [
              
            ]
          },
          {
            "title": "B.L.U.R.E.M.I.",
            "number": "6",
            "artists": [
              
            ]
          },
          {
            "title": "Battle",
            "number": "7",
            "artists": [
              
            ]
          },
          {
            "title": "Mellow Song",
            "number": "8",
            "artists": [
              
            ]
          },
          {
            "title": "Trailerpark",
            "number": "9",
            "artists": [
              
            ]
          }
        ]
      }
    ],
    "images": [
      {
        "url": "http://api.onemusicapi.com/20220401/images/discogs/2623622/1337535683-4204.jpeg",
        "width": "600",
        "height": "586"
      }
    ],
    "uris": [
      "https://www.discogs.com/release/2623622"
    ],
    "types": [
      "Album"
    ],
    "score": 1
  },
  {
    "title": "13",
    "artist": "Blur",
    "year": "1999",
    "country": "KR",
    "genres": [
      "Rock"
    ],
    "media": [
      {
        "totalDiscs": "1",
        "position": "1",
        "format": "CD",
        "tracks": [
          {
            "title": "Tender",
            "number": "1",
            "artists": [
              
            ]
          },
          {
            "title": "Caramel",
            "number": "10",
            "artists": [
              
            ]
          },
          {
            "title": "Trimm Trabb",
            "number": "11",
            "artists": [
              
            ]
          },
          {
            "title": "No Distance Left To Run",
            "number": "12",
            "artists": [
              
            ]
          },
          {
            "title": "Optigan 1",
            "number": "13",
            "artists": [
              
            ]
          },
          {
            "title": "Bugman",
            "number": "2",
            "artists": [
              
            ]
          },
          {
            "title": "Coffee & TV",
            "number": "3",
            "artists": [
              
            ]
          },
          {
            "title": "Swamp Song",
            "number": "4",
            "artists": [
              
            ]
          },
          {
            "title": "1992",
            "number": "5",
            "artists": [
              
            ]
          },
          {
            "title": "B.L.U.R.E.M.I.",
            "number": "6",
            "artists": [
              
            ]
          },
          {
            "title": "Battle",
            "number": "7",
            "artists": [
              
            ]
          },
          {
            "title": "Mellow Song",
            "number": "8",
            "artists": [
              
            ]
          },
          {
            "title": "Trailerpark",
            "number": "9",
            "artists": [
              
            ]
          }
        ]
      }
    ],
    "images": [
      {
        "url": "http://api.onemusicapi.com/20220401/images/discogs/2875045/1305136994.jpeg",
        "width": "600",
        "height": "525"
      }
    ],
    "uris": [
      "https://www.discogs.com/release/2875045"
    ],
    "types": [
      "Album"
    ],
    "score": 1
  },
  {
    "title": "13",
    "artist": "Blur",
    "year": "1999",
    "country": "UK & Europe",
    "genres": [
      "Rock"
    ],
    "media": [
      {
        "totalDiscs": "1",
        "position": "1",
        "format": "CD",
        "tracks": [
          {
            "title": "Tender",
            "number": "1",
            "artists": [
              
            ]
          },
          {
            "title": "Caramel",
            "number": "10",
            "artists": [
              
            ]
          },
          {
            "title": "Trimm Trabb",
            "number": "11",
            "artists": [
              
            ]
          },
          {
            "title": "No Distance Left To Run",
            "number": "12",
            "artists": [
              
            ]
          },
          {
            "title": "Optigan 1",
            "number": "13",
            "artists": [
              
            ]
          },
          {
            "title": "Bugman",
            "number": "2",
            "artists": [
              
            ]
          },
          {
            "title": "Coffee & TV",
            "number": "3",
            "artists": [
              
            ]
          },
          {
            "title": "Swamp Song",
            "number": "4",
            "artists": [
              
            ]
          },
          {
            "title": "1992",
            "number": "5",
            "artists": [
              
            ]
          },
          {
            "title": "B.L.U.R.E.M.I.",
            "number": "6",
            "artists": [
              
            ]
          },
          {
            "title": "Battle",
            "number": "7",
            "artists": [
              
            ]
          },
          {
            "title": "Mellow Song",
            "number": "8",
            "artists": [
              
            ]
          },
          {
            "title": "Trailerpark",
            "number": "9",
            "artists": [
              
            ]
          }
        ]
      }
    ],
    "images": [
      {
        "url": "http://api.onemusicapi.com/20220401/images/discogs/1651044/1234621066.jpeg",
        "width": "600",
        "height": "598"
      }
    ],
    "uris": [
      "https://www.discogs.com/release/1651044"
    ],
    "types": [
      "Enhanced",
      "Numbered",
      "Promo",
      "Album"
    ],
    "score": 0.74
  },
  {
    "title": "13",
    "artist": "Blur",
    "year": "1999",
    "country": "GB",
    "genres": [
      "Rock"
    ],
    "media": [
      {
        "totalDiscs": "1",
        "position": "1",
        "format": "CD",
        "tracks": [
          {
            "title": "Tender",
            "number": "1",
            "artists": [
              
            ]
          },
          {
            "title": "Caramel",
            "number": "10",
            "artists": [
              
            ]
          },
          {
            "title": "Trimm Trabb",
            "number": "11",
            "artists": [
              
            ]
          },
          {
            "title": "No Distance Left To Run",
            "number": "12",
            "artists": [
              
            ]
          },
          {
            "title": "Optigan 1",
            "number": "13",
            "artists": [
              
            ]
          },
          {
            "title": "Bugman",
            "number": "2",
            "artists": [
              
            ]
          },
          {
            "title": "Coffee & TV",
            "number": "3",
            "artists": [
              
            ]
          },
          {
            "title": "Swamp Song",
            "number": "4",
            "artists": [
              
            ]
          },
          {
            "title": "1992",
            "number": "5",
            "artists": [
              
            ]
          },
          {
            "title": "B.L.U.R.E.M.I.",
            "number": "6",
            "artists": [
              
            ]
          },
          {
            "title": "Battle",
            "number": "7",
            "artists": [
              
            ]
          },
          {
            "title": "Mellow Song",
            "number": "8",
            "artists": [
              
            ]
          },
          {
            "title": "Trailerpark",
            "number": "9",
            "artists": [
              
            ]
          }
        ]
      }
    ],
    "uris": [
      "https://www.discogs.com/release/2612875"
    ],
    "types": [
      "Album",
      "Promo"
    ],
    "score": 0.74
  }
]