This new release contains a new feature: an image endpoint. What's an image endpoint? It's a way of downloading a selection of images directly from OneMusicAPI.
So what's the big deal? Couldn't you already just download the artwork from the existing URL served up by OneMusicAPI on some-other-domain? Yep, you could, but with caveats.
The obvious caveat is that only works if the other domain allows it. Back in December we received an email from Discogs (we were Premium API customers). It said (and I paraphrase; I don't want to repeat a private email without their permission) that the terms of use would be changing, and from now on all applications can access a maximum 1000 images across a 24 hour period. That's applications, not users of an application. So any application, regardless of how many users it has, can only access 1000 images per day.
Given that a music collection in the hundreds-of-albums is hardly atypical, this is obviously a significant limitation. We immediately began to think of ways to continue serving these images.
We came up with two assumptions:
This led us to the solution: a cache of images, that will be populated over time. We introduced this for our main client, bliss, as a "back door" back in February. We've now tidied it up, moving it behind a more formalised image endpoint and so we are now ready to offer it to our other users.
How successful is the cache? Just before the Discogs API changes were enforced we grabbed a few extra images with a very slow bot that drip fed a few images. Add the results of that to the drip feeding of the cache since, and we have about 120,000 images. The most important thing, I think, is the ratio of cache hits to cache misses. Here's a graph to show how we've done, because everyone loves graphs:
Against a backdrop of steadily increasing requests on the Discogs cache, we are slowly beginning to serve more and more images from the cache, recently experiencing our first week where cache hits outstripped cache misses. Of course we'd also like to see the cache misses begin to come down as the cache increases in size, but the trend appears clear.
Using the image endpoint is pretty simple. Some release queries will return image URLs that point to the image endpoint. Here's an example:
{
"title": "The Best Christmas Album In The World...Ever!",
"artist": "Various",
"year": "2004",
"genre": "Christmas",
"media": [
...
],
"images": [
{
"url": "http://api.onemusicapi.com/20140425/images/discogs/3813006/1",
"width": "223",
"height": "225"
}
],
"score": 0.92315839219978
}
The new image endpoint URL can then be queried directly and your image downloaded:
http://api.onemusicapi.com/20140425/images/discogs/3813006/1
If you're familiar with Discogs you may already have parsed that URL in your head. That's the Discogs release ID in the URL. So, if you don't want to use OneMusicAPI for metadata, you can still use it for the Discogs image cache by simply querying using the appropriate image ID.
Note that you also need to provide your user_key, otherwise you will not be authorised
to download the image.
Also note that this change only applies to a new version of the API, version 20140425 and later. Versions prior to this do not have access to the image endpoint and queries for image information will still return the old image URLs. As ever though, we won't shutdown old versions that are being used by paying customers, so there's no huge rush!
There will be a new price plan to allow access to the image endpoint. This is to cover the cost of image storage and bandwidth. I'll be announcing this in the coming week, but if you are interested in trying this endpoint out don't hesitate to get in contact; I can get you up and running straight away.
Another major change in this release is that we have restarted returning occasional image URLs via from Amazon. From tests, this gives an extra 10% increase in cover art coverage.
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.