Does the Open Library Covers API accept work IDs?

[salomvary]

Hi folks,

I can't decide if this is a documentation issue or a bug.

The Open Library Covers API is documented to accept "OLID" which in my understanding can be both a work and an edition ID but in practice it seems to only accept work edition IDs.

E.g. this returns a 404 https://covers.openlibrary.org/b/olid/OL82563W-S.jpg?default=false despite https://openlibrary.org/works/OL82563W has a cover.

Am I missing something? Or should the documentation page be updated to use "OpenLibrary edition ID" instead of "OLID"?

[tfmorris]

but in practice it seems to only accept work IDs.

Did you mean to that it only accepts edition IDs? That would make more sense with the rest of your example and also fits with the fact that the other IDs like ISBN and OCLC are edition IDs (and works don't have covers).

When I look at that work (https://openlibrary.org/works/OL82563W), OpenLibrary perversely picks a Chinese edition as the "best," despite my language being set to French, but the cover URLs for both the Chinese and French editions resolve correctly:

https://openlibrary.org/books/OL39471692M
https://covers.openlibrary.org/b/olid/OL39471692M-S.jpg?default=false
https://openlibrary.org/books/OL31386308M
https://covers.openlibrary.org/b/olid/OL31386308M-S.jpg?default=false

[cdrini]

The Chinese edition being chosen is because that page, unlike the search page, is not using the solr-based "best" edition choosing algo I describe below. Issue welcome.

[tfmorris]

Actually, https://openlibrary.org/works/OL82563W.json has more than a dozen cover IDs listed, so, arguably, this could be a bug, but, in my opinion, you're better off choosing your own best / most representative edition and using it's cover.

[salomvary]

Did you mean to that it only accepts edition IDs?

Yep, sorry, I mean that. At least I got the question in the title of the discussion right :)

I was looking for a quick way where I only have a work ID and want a cover for that, leave OpenLibrary API choose whatever it judges to be "best".

Seems like we don't have a conclusion whether this is a bug or non-existent feature :)

[cdrini]

If you have an open library work ID and want to get the "best" associated edition/cover, the search.json API is your best bet. Eg:

https://openlibrary.org/search.json?q=key%3A%22%2Fworks%2FOL82563W%22&mode=everything&fields=key,author_key,author_name,editions,editions.key,editions.title,editions.subtitle,editions.language,editions.cover_i

Note you have to specify editions in the fields parameter to get it to choose the best edition.

Here, best edition will try to choose:

1. The edition best matching the query (eg if you search for "chambres des secrets", it'll match the french edition regardless of your browser language) . Although this doesn't impact anything if you are searching by an explicit work key.
2. The edition matching the browser's language, as set by the HTTP Accept-Language header. You can also test/override this by specifying the lang param, eg
   https://openlibrary.org/search.json?q=key%3A%22%2Fworks%2FOL82563W%22&mode=everything&fields=key,author_key,author_name,editions,editions.key,editions.title,editions.subtitle,editions.language,editions.cover_i&lang=fr (note the selected edition is now in french)
3. An edition that is borrowable or previewable or readable

Not sure your use case, but if you do end up using this, please don't fetch one work per request! That's a perf strain on our end. You can fetch them in batches, which is faster for both you and us. E.g. key:("/works/OL82563W" OR "/works/OL82537W" OR "/works/OL82536W")

Does this meet your use case?

[salomvary]

Thanks a lot, good suggestion on picking a cover from the editions, we already use something similar to pick a title to represent a work.

No worries about API usage, we use our own database populated from dumps.

I guess one last thing would for someone who has write permission to edit https://openlibrary.org/dev/docs/api/covers and make it crystal clear that https://covers.openlibrary.org/b/olid/$value-$size.jpg only accepts edition IDs.