After a few months of development, the new release of OneMusicAPI is now released! There's a whole bunch of additional features in the new version including general release metadata, disc queries and vastly improved coverage for Acoustid fingerprint and MusicBrainz disc ID queries. OneMusicAPI also now supports FreeDB queries for discs!
First things first: to use the new version you'll have to use a new endpoint. As part of our promise to existing customers the one existing version of OneMusicAPI will not be disabled and will continue to function as before. To use the new version you'll have to use the new endpoint:
http://api.onemusicapi.com/20130307/...
Some actual examples are below...
For queries that return information about releases, we've now added further metadata including year, genre and track information. Here's an example query:
http://api.onemusicapi.com/20130307/release?title=Play&artist=Moby
Remember you'll need to add your user_key (signup here!). And the results...
[
{
"title": "Play",
"artist": "Moby",
"year": "1999",
"genre": "Electronica",
"media": [
],
"images": [
],
"score": 1
},
{
"title": "Play",
"artist": "Moby",
"year": "1999",
"genre": "Electronic",
"media": [
{
"tracks": [
{
"title": "Honey",
"number": "1",
"artist": ""
},
{
"title": "Find My Baby",
"number": "2",
"artist": ""
},
{
"title": "Porcelain",
"number": "3",
"artist": ""
}
...
]
}
]
},
...
]
A couple of goodies to notice here... First, "inc=images" is no longer mandatory. You can
omit it if you don't want cover art.
Next, you can see a lot more metadata than before. Titles, artists, year, genre and track information are all included.
There's now a new /disc endpoint added to the API to support writers of CD-oriented software
and hardware. Why's that? Well, in the case of multi disc releases, CD oriented products need to be mindful
of which disc they are displaying information about.
OneMusicAPI now offers a /disc endpoint which accepts any number of Acoustid fingerprints,
MusicBrainz disc IDs and FreeDB disc IDs. Here's an example query, just with a MusicBrainz disc ID:
http://api.onemusicapi.com/20130307/disc?musicBrainzDiscId=0tffAN0PLpn1Lc4yM7uoeOajAGM-
This is a query for the second CD of 4hero's Two Pages. The results (much abridged)...
{
"disc_match": {
"position": "2",
"tracks": [
{
"title": "We Who Are Not as Others",
"number": "1",
"artist": "4hero"
},
{
"title": "Humans",
"number": "2",
"artist": "4hero"
},
{
"title": "In the Shadows",
"number": "3",
"artist": "4hero"
},
...
]
},
"associated_releases": [
{
"title": "Two Pages",
"artist": "4hero",
"year": "1998",
"genre": "broken beat",
"media": [
{
"position": "1",
"tracks": [
{
"title": "Loveless (feat. Ursula Rucker)",
"number": "1",
"artist": "4hero,Ursula Rucker"
},
{
"title": "Golden Age of Life",
"number": "2",
"artist": "4hero"
},
{
"title": "Planeteria (A Theme From a Dream)",
"number": "3",
"artist": "4hero"
},
...
]
},
{
"position": "2",
"tracks": [
{
"title": "We Who Are Not as Others",
"number": "1",
"artist": "4hero"
},
{
"title": "Humans",
"number": "2",
"artist": "4hero"
},
{
"title": "In the Shadows",
"number": "3",
"artist": "4hero"
},
...
]
}
]
}
...
]
}
The latter associated_releases object contains all release information that could be found
in the same way the existing release endpoint does. It's the former disc_match
object which is important to CD oriented products. This shows the information just for the CD that was
sent in the query, identified in this example by the MusicBrainz Disc ID. You can also see that while just the information
for the second disc is present in disc_match, associated_releases also contains
information for the first disc should you need it.
There's also a special feature available to disc queries... aggregated. If set to
"first" then OneMusicAPI creates an extra object at the start of the response containing
the first occurence of each field found in all of the results. This is really useful if you just want to interrogate
one object:
http://api.onemusicapi.com/20130307/disc?musicBrainzDiscId=0tffAN0PLpn1Lc4yM7uoeOajAGM-&aggregated=first&inc=images
Here are the results:
{
"aggregated": {
"title": "Two Pages",
"artist": "4hero",
"year": "1998",
"genre": "broken beat",
"image": "http://api.discogs.com/image/R-9937-1143266804.jpeg",
"tracks": [
{
"title": "We Who Are Not as Others",
"number": "1",
"artist": "4hero"
},
{
"title": "Humans",
"number": "2",
"artist": "4hero"
},
{
"title": "In the Shadows",
"number": "3",
"artist": "4hero"
},
...
]
},
"disc_match": {
"position": "2",
"tracks": [
{
"title": "We Who Are Not as Others",
"number": "1",
"artist": "4hero"
},
{
"title": "Humans",
"number": "2",
"artist": "4hero"
},
{
"title": "In the Shadows",
"number": "3",
"artist": "4hero"
},
...
]
},
"associated_releases": [
...
]
}
Notice how all information, including cover art, year and genre, are included in that first result along with the correct track listing for that disc. Handy!
In the previous version of the API, results for Acoustid fingerprints and MusicBrainz Disc IDs weren't as successful as simple tag based title queries. The reason was two-fold. First, only MusicBrainz was interrogated for those queries, so the possible set of matches was decreased. Second, and more importantly, cover art was the only data returned and MusicBrainz only has around 10% of its releases containing cover art sourced from the Cover Art Archive (at the time of writing).
The queries that OneMusicAPI sends have now been shuffled so that the queries work together. If, for example, the barcode of a release is found on MusicBrainz, that barcode is then used to query Discogs. This means the data sources for OneMusicAPI work together a lot better and return many more results.
That's enough for now. To give OneMusicAPI a try all you need to do is sign up and you'll get 1000 free queries. Further queries can be purchased on a rolling monthly basis or as a credit top-up. When you do sign up, use the new reference documentation that has been released.