Thursday, August 7th, 2008

A million free covers from LibraryThing

A few days ago, just before hitting thirty million books, we hit one million user-uploaded covers. So, we’ve decided to give them away—to libraries, to bookstores, to everyone.

The basics. The process, patterned after the Amazon.com cover service, is simplicity itself:

  1. Take an ISBN, like 0545010225
  2. Put your Developer Key and the ISBN into a URL, like so:
    http://covers.librarything.com/devkey/KEY
    /medium/isbn/0545010225
  3. Put that in an image tag, like so:
    <img src="http://covers.librarything.com/devkey/KEY/medium/isbn/0545010225">
  4. And your website, library catalog or bookstore has a cover.

Easy details. Each cover comes in three sizes. Just replace “medium” with “small” or “large.”

As with Amazon, if we don’t have a cover for the book, we return a transparent 1×1 pixel GIF image. So you can put the cover-image on OPAC pages without knowing if we have the image. If we have it, it shows; if we don’t, it doesn’t.

The Catch? To get covers, you’ll need a LibraryThing Developer Key—any member can get one. This puts a top limit on the number of covers you can retrieve per day—currently 1,000 covers. In fact, we only count it when a cover is made from the original, o our actual limit will be much higher. We encourage you to cache the files locally.

You also agree to some very limited terms:

  • You do not make LibraryThing cover images available to others in bulk. But you may cache bulk quantities of covers.
  • Use does not involve or promote a LibraryThing competitor.
  • If covers are fetched through an automatic process (eg., not by people hitting a web page), you may not fetch more than one cover per second.

You will note that unlike the new API to our Common Knowledge data, you are not required to link back to LibraryThing. But we would certainly appreciate it.

Caveats. Some caveats:

  • At present only about 913,000 covers are accessible, the others being non-ISBN covers.
  • Accuracy isn’t guaranteed–this is user data–and coverage varies.
  • Some covers are blurrier than we’d like, particularly at the “large” size. This is sometimes about original files and sometimes about our resizing routines. We’re working on the latter.

Why are you doing this? The goal is half promotional and half humanitarian.

First, some background. This service “competes” with Amazons cover service, now part of Amazon Web Services. Amazon’s service is, quite simply, better. They have far more covers, and no limit on the number of requests. By changing the URL you can do amazing things to Amazon covers.

The catch is that Amazon’s Terms of Service require a link-back. If you’re trying to make money from Amazon Affiliates, this is a good thing. But libraries and small bookstores have been understandably wary about linking to Amazon. Recent changes in Amazon’s Terms of Service have deepened this worry.

Meanwhile, there are a number of commercial cover providers. They too are probably, on average, better. But they cost money. Not surprisingly many libraries and bookstores skip covers, or paste them in manually from publisher sites.

That’s too bad. Publishers and authors want libraries and bookstores to show their covers. Under U.S. law showing covers to show off books for sale, rental or commentary falls under Fair Use in most circumstances. (We are not lawyers and make no warrant that your use will be legal.) We’ve felt for years that selling covers was a fading business. Serving the files is cheap and getting cheaper. It was time for someone to step up.*

So we’re stepping up. We’re hoping that by encouraging caching and limiting requests, we can keep our bandwidth charges under control. (If it really spikes, we’ll limit new developer keys for a while; if you submit this to Slashdot, we will be Slashdotted for sure!) And it will be good for LibraryThing—another example of our open approach to data. Although none of our competitors do anything like this—indeed our Facebook competitors don’t even allow export although, of course, they import LibraryThing files!—we think LibraryThing has always grown, in part, because we were the good guys—more “Do occasional good” than “Do no evil.”

If we build it, they will come. If the service really pick up, we’re going to add a way for publishers, bookstores and authors to get in on it. We’d be happy to trade some bandwidth out for what publishers know—high-quality covers, author photos, release dates and so forth. We’ve already worked with some publisher data, but we’d love to do more with it.


*In the past, we had been talking to the Open Libary project about a joint effort. We even sent them all our covers and a key to the identifiers that linked them. But nothing came of it. To some extent that was our fault, and to some extent not. (I think them and us would differ on the blame here.) In any case, I was tired of the time and transactional friction, and wanted to try a different approach.

Labels: apis, book covers, covers, open data

30 Comments:

  1. Anonymous says:

    There is an error when I was trying to get bookcover. It keeps redirecting to an coverthing404.php page.

    Is there something wrong with LT book cover?

  2. Anonymous says:

    The URL starting with http://covers.librarything.com … doesn't work. Changing it to http://www.librarything.com … fixes the problem.

  3. Susie says:

    I still can't get the covers to show up even using the address change and all the covers that I had, have disappeared!

  4. suja says:

    I have the same problem..

    "There is an error when I was trying to get bookcover. It keeps redirecting to an coverthing404.php page"

    Someone please help…

  5. Anonymous says:

    I am a church librarian and want to pirnt book covers so that I can put them on a bulletin board outside the libary. What is a devkey? How do I obtain one?

  6. SCC says:

    Hai,

    I need to get the number of images i have downloded today and what is limit remaining today using API ,

    How can i get that , Please help me !!

  7. Chuck says:

    Hey, the only cover I can retrieve is the harry potter one (the example). None of the other ISBNs I’ve tried return an image. What’s up? Is this API for real?

  8. I hadn’t read or heard about this story. Thanks for sharing. How cool!

  9. Nick Jackson says:

    Is there any way to make it return a 404 if the cover doesn’t exist instead of a blank 1px image? The Open Library covers API has this feature (http://openlibrary.org/dev/docs/api/covers), but I’d rather use LibraryThing since it lets us cache the images.

    If all else fails I’m cool with checking the images in my code, just rather take the easy route if there is one.

  10. SeveQ says:

    I’ve got the same problem as Chuck mentioned on July the 1st last year. There’s only one cover that I can retrieve through the API (the one from the example). No other ISBN seems to work.

  11. sarahbee says:

    Doesn’t work for me either. The book page says the cover image I am looking for is available in 1128×1718, but the only image I can call up with this method is the thumbnail 140×213 size. I tried using each of the “small” “medium” and “large” descriptors in the URL. All three returned the thumbnail. What am I doing wrong?

  12. SunnyNM says:

    As sarahbee says, The high resolution,i.e.1128×1718, images shown will only display when clicked on as large, i.e. ~140×213 size images. If the intention is not to allow their downloading, why post their resolution? I assume they are to be available in the high res. size so how is this to be accomplished?

  13. jouni miettunen says:

    Just asking for status update: 4 years ago you had 1 million cover, howabout now? Is this API still available? Is there any way to access the non-ISBN covers i.e. have you figured out a way to map them to some other unique identifiers (oh, forgot ISBN isn’t unique either)?

  14. jlundgren says:

    If I want to add covers (so they display via the API) what is the best way to do so? I can go into my LibraryThing account, add the book and change the cover to one I upload – but I am not seeing the cover via the API.

    Is there a lag time? An approval process? How long does it take my user-uploaded cover to be accessible via API?

    thanks.

  15. kwilkins says:

    Any chance we can get some ssl support? We would love to use this in our campus portal but it needs to be over https.

  16. Greg says:

    Is this still supported? I can only get very few ISBN to return a cover image. It appears that librarything is using amazon’s cover image services now? Is that true?

    I just want to get 4 to 8 images a month and cache them. Is this API the best way to do that?

  17. Derek says:

    This API appears to be abandoned and unworking. Even cover images that show in the library thing software, do not produce an image when you use this api.

  18. Tim says:

    The API only returns LibraryThing member-uploaded covers. As many images “shown in the LibraryThing software” are really from Amazon or elsewhere, many will not show up in the API.

    Post on Talk with specifics if you want to troubleshoot.

  19. Howard Richoux says:

    this is a potentially nice feature, BUT…. This retrieval API is totally different from the documented developer API. While viewing this page, use your browser to look at the link for some of the other covers shown and you can figure out the methodology. (also note that some developer key shows up in the link…)

    After I figured out how to stuff my developer key into this URL, I started retrieving various ISBNs I was testing with and got bad results (although some of the bad results started with the string “GIF89a” so it would not surprise me that some of the covers are jpgs and some are gifs.

    This API has promise, but the documentation is weak.

  20. I tried the API today in April 2017. I tried to get 1200 images of the newest bought books from _german_ libraries. I got 2 images in the best case.

    I thought this is a problem with german books only, but when reading the comments I think this API has nearly no covers in its database anymore.

    • Loranne says:

      Sorry to hear about the API trouble! Would you mind emailing us at info@librarything.com with more details? I’ll be happy to have our developers take a look.

      It’s also worth noting that our APIs have a maximum of 1,000 requests per day. Since you mention trying to get 1,200 of them, it that may be the source of the issue.

  21. I am trying to download and print some book covers. I do not have a website or store or library catalog. I do have a developer key. I tried to follow the directions to obtain a book cover, but it just takes me back to a Google search results page. I need step-by-step oversimplified instructions. Sorry foe being an idiot!

    Kind Regards,

    Robert

    • Loranne says:

      Please email us at info@librarything.com with a detailed description of the issue (which API you’re using, your LT username, what exactly happens/what the Google search results page says, etc.), and we’ll be happy to help you from there. Sorry for the trouble!

  22. John Fones says:

    I’d like to see this expanded – perhaps as a pilot in the first instance – so that we can use images of book spines as well.
    This could be combined with the book dimension data (although it seems that thickness is currently referred to as “length” in the exported spreadsheet format) to allow creation of shelving simulations that could reflect the way we store our books – could even direct the way we store our books.
    Currently looking into a project to do just this.

  23. Simon Hewitt says:

    The server for covers has returned Server Unavailable for the last few days. It’s not a devkey issue as that works fine on the REST APIs.

    e.g.
    http://covers.librarything.com/devkey//large/isbn/9798072141837

    • Unfortunately we have suspended all developer keys for LibraryThing at the moment (they were being abused more than we could handle, and we need to figure out how to prevent that in the future). Please check back with us at a later date!

  24. Simon Hewitt says:

    Have you guys given up with the APIs?

    • Unfortunately we have suspended all developer keys/APIs for LibraryThing at the moment (they were being abused more than we could handle, and we need to figure out how to prevent that in the future). Please check back with us at a later date!

  25. Kevin says:

    The url http://covers.librarything.com/devkey/KEY
    /medium/isbn/0545010225 (including the dev key) has been returning 503 for a few days now. Is this request still operational?

    • Unfortunately we have suspended all developer keys/APIs for LibraryThing at the moment (they were being abused more than we could handle, and we need to figure out how to prevent that in the future). Please check back with us at a later date!

Leave a Reply