This is documentation for version 20150623 which is deprecated. The current version is 20151208. We will continue to make deprecated versions available to customers who still use them, but new customers should use the latest version.

Querying releases

GET /20150623/release
POST /20150623/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.

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.

Examples

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

Retrieves the images for Thriller by Michael Jackson.

/20150623/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.

Examples

/20150623/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 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 Acoustid fingerprint queries, return the input track.[m.]n parameter that matched each track on a 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

/20150623/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.

/20150623/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": "habits",
    "artist": "Neon Trees",
    "media": [
      {
        "tracks": [
          {
            "title": "Sins Of My Youth",
            "number": "1"
          },
          {
            "title": "Love And Affection",
            "number": "2"
          },
          {
            "title": "Animal",
            "number": "3"
          },
          {
            "title": "Your Surrender",
            "number": "4"
          },
          {
            "title": "1983",
            "number": "5"
          },
          {
            "title": "Girls And Boys In School",
            "number": "6"
          },
          {
            "title": "In The Next Room",
            "number": "7"
          },
          {
            "title": "Our War",
            "number": "8"
          }
        ]
      }
    ],
    "score": 1
  },
  {
    "title": "Habits",
    "artist": "Neon Trees",
    "year": "2011",
    "genre": "Rock",
    "media": [
      {
        "tracks": [
          {
            "title": "Sins Of My Youth",
            "number": "1",
            "artist": ""
          },
          {
            "title": "Love And Affection",
            "number": "2",
            "artist": ""
          },
          {
            "title": "Animal",
            "number": "3",
            "artist": ""
          },
          {
            "title": "Your Surrender",
            "number": "4",
            "artist": ""
          },
          {
            "title": "1983",
            "number": "5",
            "artist": ""
          },
          {
            "title": "Girls And Boys In School",
            "number": "6",
            "artist": ""
          },
          {
            "title": "In The Next Room",
            "number": "7",
            "artist": ""
          },
          {
            "title": "Our War",
            "number": "8",
            "artist": ""
          }
        ]
      }
    ],
    "images": [
      {
        "url": "http://api.onemusicapi.com/20140925/images/discogs/2719042/1297955038",
        "width": "600",
        "height": "600"
      }
    ],
    "score": 1
  }
]
comments powered by Disqus
© 2012-2018 elsten software limited, Unit 4934, PO Box 6945, London, W1A 6US, UK | terms and conditions | privacy policy