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.
GET /20171116/release POST /20171116/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.
All queries must contain the following:
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 |
| 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. |
ReleaseLabel| Field | Type | Description |
|---|---|---|
| name | String | The name of the record label. |
| cat | String | The cat number for the release. |
A name based query must include:
inc=trackMatch is also used.format=vinyl/20171116/release?user_key=myUserKey&inc=images&title=Thriller&artist=Michael%20Jackson
Retrieves the images for Thriller by Michael Jackson.
/20171116/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.
OneMusicAPI accepts Acoustid fingerprints in queries.
inc=trackMatch is also used.inc=trackMatch is also used.
Use the Acoustid 'fp_calc' tool to generate fingerprints.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.
format=vinyl/20171116/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 Table Of Contents queries can be sent to OneMusicAPI.
MusicBrainz Disc ID queries can be sent to OneMusicAPI.
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.
Queries for releases given its barcode.
format=vinylIn addition, all queries can be further constrained with the following parameters:
inc is set then the following additional items may be retrieved:
track.[m.]n parameter that matched each track on a release.inc, if this parameter is set then the following additional items may be retrieved:
/20171116/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.
/20171116/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.
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/20171116/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/20171116/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/20171116/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/20171116/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
}
]
comments powered by Disqus