We're proud to announce a new version of OneMusicAPI... the biggest addition being artist metadata searches! We've also made several improvements to release queries; allowing query by Discogs release ID and also allowing "unknown" positions for tracks in fingerprint queries.
The changes in the API for this release means we've introduced a new API version, 20140925,
which we encourage all clients to migrate to. But as ever, we won't stop older versions whilst
paying customers are using them!
Up to now, OneMusicAPI has been very release oriented. You could retrieve information about albums, EPs and singles. Later we added disc queries, but even that is kinda related to releases (kinda ;-) ).
By far the biggest requested feature was artist metadata retrieval. Want pictures of Lady Gaga? Want to know all of the aliases of Aphex Twin? Now you can find all of this information and more using OneMusicAPI.
So how can artists be queried, and what type of data is returned? There are currently two types of query: a simple name based query, and a Discogs artist ID query. Let's look at both, and while we do so we can see the type of data that is returned.
Named based queries take, as an argument, the name or alias of a musical artist and return all artists that match:
http://api.onemusicapi.com/20140925/artist?called=Beatles
This gives:
[
{
"name": "Beatles, The",
"aliases": [
"fab four",
"披头士",
"Los Beatles",
"Beatles*",
"Битлз",
"披頭四",
"Beatles",
[...]
],
"images": [
{
"url": "http://api.discogs.com/images/A-82730-1319373922.jpeg",
"width": "578",
"height": "567"
},
{
"url": "http://api.discogs.com/images/A-82730-1319532293.jpeg",
"width": "501",
"height": "567"
},
[...]
],
"urls": [
"http://www.45cat.com/artist/the-beatles",
"https://plus.google.com/111520018934389590684",
"http://lyrics.wikia.com/The_Beatles",
"http://www.discogs.com/artist/82730",
"http://www.thebeatles.com/",
[...]
],
"score": 1
}
]
(Truncated for readability). The called parameter queries both all known aliases
and also the actual name of artists. You can see we currently return the name, aliases, images
and other URLs associated with this artist.
The other type of query possible are Discogs artist ID queries:
http://api.onemusicapi.com/20140925/artist?discogsId=45
... gives:
[
{
"name": "Richard David James",
"aliases": [
"Apex Twin",
"AFX",
"A.Twin",
"Aphex Twins",
"TheAphexTwin",
"A-F-X Twin",
"A.F.X.",
"Aphex Twin, The"
],
"images": [
{
"url": "http://api.discogs.com/images/A-45-1408907021-4444.jpeg",
"width": "600",
"height": "600"
},
{
"url": "http://api.discogs.com/images/A-45-1414874002-9310.jpeg",
"width": "848",
"height": "600"
},
[...]
],
"urls": [
"http://www.littlebig-agency.net/artists/aphex-twin/",
"http://warp.net/records/aphex-twin",
[...]
],
"score": 1
}
]
Querying by Discogs ID may be useful where you have the ID already available.
A smaller improvement, but still useful, is the ability to query releases by Discogs ID. Many music files may have Discogs IDs embedded, so using those is a quick and easy way of accurately looking up metadata about that release. The real power of Discogs ID lookup is that data from other sources are also returned. OneMusicAPI links the Discogs release to, say, the MusicBrainz release to provide even more data:
http://api.onemusicapi.com/20140925/release?discogsId=4170983&inc=images
... gives:
[
{
"title": "Generation Terrorists",
"artist": "Manic Street Preachers",
"year": "1992",
"genre": "Rock",
"media": [
{
"tracks": [
{
"title": "Slash N' Burn",
"number": "1",
"artist": ""
},
[...]
}
],
"images": [
{
"url": "http://api.onemusicapi.com/20140925/images/discogs/4170983/1373019876-4579",
"width": "599",
"height": "600"
},
{
"url": "http://api.onemusicapi.com/20140925/images/discogs/411909/1251318645",
"width": "600",
"height": "600"
},
{
"url": "http://api.onemusicapi.com/20140925/images/discogs/5839277/1404163498-2767",
"width": "593",
"height": "600"
},
{
"url": "http://coverartarchive.org/release/57ee1f37-3247-4228-9ba1-9dc51fac97f6/2227145745.jpg",
"width": "600",
"height": "600"
},
{
"url": "http://coverartarchive.org/release/57ee1f37-3247-4228-9ba1-9dc51fac97f6/7045748560.jpg",
"width": "953",
"height": "953"
}
[...]
],
"score": 1
}
]
There we can see images combined from both MusicBrainz and Discogs, having queried with just the Discogs release ID.
Before now, OneMusicAPI's audio fingerprinting lookups have required knowledge of the track position for each track of the release you are trying to query. This works when the track position is known, but when it is unknown (e.g. for completely untagged files) we could not return a result.
Now we can! In addition to the track.1.fingerprint syntax, we now support track.unknown1.fingerprint
http://api.onemusicapi.com/20140925/release?track.unknown1.duration=270&track.unknown1.fingerprint=AQABz_kTldCRH00[...]&track.unknown2.duration=313&track.unknown2.fingerprint=AQABz7LUI365[...]
So why is there a distinct integer next to each "unknown"? This helps with another improvement - trackMatch!
trackMatch
http://api.onemusicapi.com/20140925/release?inc=trackMatch&track.unknown1.duration=270&track.unknown1.fingerprint=AQABz_kTldCRH00[...]
This gives a new match object inside each track:
[
{
"title": "Scott 4",
"artist": "Scott Walker",
"year": "1992",
"media": [
{
"tracks": [
{
"title": "The Seventh Seal",
"number": "1",
"artist": "Scott Walker",
"match": {
"trackNumber": "unknown2"
}
},
[...]
{
"title": "Hero of the War",
"number": "6",
"artist": "Scott Walker",
"match": {
"trackNumber": "unknown1"
}
},
[...]
You can see that the match object correlates to the query that was sent. Here, unknown1
was actually the sixth track in the release results.
Note, then, that the unknownN position given for each track is used only to provide a
correlation to the trackMatch object - it is not used to match or score results. This means
that if you are not interested in trackMatch you can use whatever integer you like...
There are plenty of other performance, coverage and accuracy improvements in this release. I suggest all clients upgrade to this release but don't worry, as ever we won't retire existing versions of the API when people are still using them!
Thanks to j0mammma who made the the image above available for sharing.