Querying releases

GET /20130130/release
POST /20130130/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.
inc: The data to return. Currently only images is supported.

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.n.name: Specify the name for a track, where 'n' is the track number. Useful for getting better quality and more accurate results when querying with just album and artist names.

Examples

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

Retrieves the images for Thriller by Michael Jackson.

/20130130/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.n.duration: The duration of a track in seconds, where 'n' is an integer denoting the track number. This is to support Acoustid fingerprint based lookups.
track.n.fingerprint: The Acoustid fingerprint for a track, where 'n' is an integer denoting the track number. Use the Acoustid 'fp_calc' tool to generate fingerprints.

Examples

/20130130/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.n.offset: The offset of a track on a CD's TOC, 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.

Optional parameters for all queries

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

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 10.
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.

Examples

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

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

/20130130/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:

{
"releases" : [
  {
  "title" : "Thriller",
  "artist" : "Michael Jackson",
  "year" : "1980",
  "genre" : "Pop",
  "images" : [
    {
    "url" : "http://upload.wikimedia.org/wikipedia/en/5/51/Michaeljacksonthrilleralbum.jpg",
    "width" : "300",
    "height" : "298"
    }
  ],
  "score" : "1.0"
  }
]
}