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

Querying discs

GET /20171116/disc
POST /20171116/disc

Searches for information about CDs. Queries to /disc must be either a FreeDB query, an Acoustid fingerprint 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, especially for Acoustid queries, can otherwise get too long.

Mandatory parameters for all queries

All queries must contain the following:

user_key
Your API key.

FreeDB query

A FreeDB query specifies a FreeDB disc ID alongside a CD Table Of Contents. The TOC is required to both query FreeDB and validate results. A FreeDB query must include:

Mandatory parameters

freeDbDiscId
A FreeDB disc ID to use to lookup the data.
track.[m.]n.offset
The offset of a track on a CD's TOC, where 'm' is the optional medium number and 'n' is an integer denoting the track number.
track.leadout.offset
The offset of the leadout track in a CD's TOC (this is also the end offset of the final track).

Offsets must be sent for every track and the leadout track for the results to be validated.

Examples

/20171116/disc?user_key=myUserKey&freeDbDiscId=4f06d108&track.1.offset=150&track.2.offset=16541
&track.3.offset=30314&track.4.offset=46236&track.5.offset=62800&track.6.offset=79492&track.7.offset=95384
&track.8.offset=112719&track.leadout.offset=131099

Retrieves information about habits by Neon Trees.

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 integer denoting the track number. This is to support Acoustid fingerprint based lookups.
track.[m.]n.fingerprint
The Acoustid fingerprint for a track, where 'm' is the optional medium number and 'n' is an integer denoting the track number. Use the Acoustid 'fp_calc' tool to generate fingerprints.

Examples

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

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

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:

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 disc.
trackMatch
For Acoustid fingerprint queries, return the input track.[m.]n parameter that matched each track.
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.
If the requested data is not available, the disc 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 disc.
If the requested data is not available, the disc information 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 disc. 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.
aggregated
Either "off" (the default) or "first". If "first", then provides an aggregated object in which each field is populated with the first occurrence of each datum.

Response

Here's an example response: 

http://api.onemusicapi.com/20171116/disc?freeDbDiscId=4f06d108&track.1.offset=150&track.2.offset=16541&track.3.offset=30314&track.4.offset=46236&track.5.offset=62800&track.6.offset=79492&track.7.offset=95384&track.8.offset=112719&track.leadout.offset=131099&inc=images&maxResultCount=20&aggregated=first
{
  "aggregated":{
    "title":"habits",
    "artist":"Neon Trees",
    "year":"2011",
    "genre":"Rock",
    "image":"http://api.onemusicapi.com/20140925/images/discogs/2719042/1297955038",
    "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"
    }]
  },
  "disc_match":{
    "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"
    }]
  },
  "associated_releases":[{
    "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"
      }]
    }],
    "images":[],
    "score":1.0
  },{
    "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.0
  },{
    "title":"Habits",
    "artist":"Neon Trees",
    "year":"2010",
    "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/2245012/1272219288",
      "width":"600",
      "height":"600"
    }],
    "score":1.0
  },{
    "title":"Habits",
    "artist":"Neon Trees",
    "year":"2010",
    "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/3939321/1349981625-8754",
      "width":"589",
      "height":"595"
    }],
    "score":1.0
  }]
}

Because aggregated was set to first, the aggregated object contains the first occurrence of each datum of interest. Subsequently, the disc_match provides information about the track listing for this particular disc. Finally, associated_releases provides more metadata concerning the releases that this disc was part of.

comments powered by Disqus
© 2012-2024 elsten software limited, Unit 4934, PO Box 6945, London, W1A 6US, UK | terms and conditions | privacy policy