/dev/docs/api/covers
Type: /type/page
body: value: Our Covers API provides a programmatic method to access the book covers and author photos available in the Open Library Covers Repository.

<h2>Guidelines for Cover Use</h2>

 1. Please, **do not crawl our cover API**. If you do, we may decide to block your crawl. Our covers are available for download in bulk on archive.org ([example][1]), but, it's a bit of a jungle in there, and is updated regularly. 
 2. If you want to display covers on public-facing pages, please use a src URL that points to covers.openlibrary.org. For example, if you'd like to call a cover using an ISBN, you can do it like this: <br />`<img src="https://covers.openlibrary.org/b/isbn/9780385533225-S.jpg" />`
 3. A courtesy link back to Open Library is appreciated, whether it be on each individual book's page (where you can link back to the book's page on Open Library, for example, using the same ISBN `https://openlibrary.org/isbn/9780385533225`), or on your About page or in your footer. 

Thanks!

<h2>How To</h2>

Book covers can be accessed using Cover ID (internal cover ID), OLID (Open Library ID), ISBN, OCLC, and LCCN.

The covers are available in 3 sizes: 

 1. <b>S</b>: Small, suitable for use as a thumbnail on a <a href="https://openlibrary.org/works/OL5734718W/Little_Brother#lists-section">lists section of a work</a> on Open Library, 
 2. <b>M</b>: Medium, suitable for display on a <a href="https://openlibrary.org/books/OL5218962M">details page</a> on Open Library and,
 3. <b>L</b>: Large

The URL pattern to access book covers is:

`https://covers.openlibrary.org/b/$key/$value-$size.jpg`

Where:

 - `key` can be any one of ISBN, OCLC, LCCN, OLID and ID (case-insensitive)
 - `value` is the value of the chosen key
 - `size` can be one of S, M and L for small, medium and large respectively.

By default it returns a blank image if the cover cannot be found. If you append `?default=false` to the end of the URL, then it returns a 404 instead.

The following example returns small sized cover image for book with ISBN 0385472579.

<a href="https://covers.openlibrary.org/b/isbn/0385472579-S.jpg">https://covers.openlibrary.org/b/isbn/0385472579-S.jpg</a>

The same cover can be accessed in multiple ways using different keys:

<img src="https://covers.openlibrary.org/b/isbn/0385472579-S.jpg" /><br />

 - https://covers.openlibrary.org/b/id/240727-S.jpg
 - https://covers.openlibrary.org/b/olid/OL7440033M-S.jpg
 - https://covers.openlibrary.org/b/isbn/0385472579-S.jpg
 - https://covers.openlibrary.org/b/isbn/9780385472579-S.jpg
 - https://covers.openlibrary.org/b/lccn/93005405-S.jpg
 - https://covers.openlibrary.org/b/oclc/28419896-S.jpg

<h2>Author Photos</h2>

Author photos can be accessed using OLID and ID.

The URL Pattern for accessing author photos is:

`https://covers.openlibrary.org/a/$key/$value-$size.jpg`

For example the following is the photograph of <a href="https://openlibrary.org/a/OL229501A">Donald E. Knuth</a> from the Open Library.

<img src="https://covers.openlibrary.org/a/id/3365456-S.jpg" />

   * https://covers.openlibrary.org/a/olid/OL229501A-S.jpg

  [1]: https://www.archive.org/details/covers_0005
  
<a name="rate-limiting">&nbsp;</a>

<h2>Cover Size & API Access</h2>

You can add `.json` to end end of cover urls to return API information about the cover, e.g. `https://covers.openlibrary.org/b/id/12547191.json`.

One can fetch the image off-screen and use it's width/height:

<pre>
async function fetchImage(url) {
    const img = new Image();
    return new Promise((res, rej) => {
        img.onload = () => res(img);
        img.onerror = e => rej(e);
        img.src = url;
    });
}

const img = await fetchImage('https://covers.openlibrary.org/b/id/12547191-L.jpg');
const w = img.width;
const h = img.height;
</pre>

This one way one won't need to make two separate requests per image! The browser won't make a second request for the image if you set the src of your visible `<img>` element after fetching it in this way.

<h2>Rate Limiting</h2>

The cover access by ids other than CoverID and OLID are rate-limited. Currently only 100 requests/IP are allowed for every 5 minutes. 

If any IP tries to access more that the allowed limit, the service will return "403 Forbidden" status.

<a name="bulk-access">&nbsp;</a>

<h2>Bulk Access</h2>

The covers API is intended for displaying covers on public facing websites and not for bulk download.

If you are interested to download the covers in bulk, please download them from:

* Small Covers: 

    * <https://www.archive.org/details/s_covers_0000>
    * ...
    * <https://www.archive.org/details/s_covers_0006>

* Medium Covers:

    * <https://www.archive.org/details/m_covers_0000>
    * ...
    * <https://www.archive.org/details/m_covers_0006>

* Large Covers:

    * <https://www.archive.org/details/l_covers_0000>
    * ...
    * <https://www.archive.org/details/l_covers_0006>

* Original Covers:

    * <https://www.archive.org/details/covers_0000>
    * ...
    * <https://www.archive.org/details/covers_0005>
    
Each of these archive.org items have 100 tar files, each containing 10K images in each. The names of these files are based on the cover ids. For example, `s_covers_0005_32.tar` file contains images for CoverIDs from `5320000` to `5329999`.

The mapping from various IDs to CoverIDs is available at:

<https://www.archive.org/download/ol_dump_2011-03-31/ol_dump_coverids_2011-03-31.txt.gz>

It has 4 columns ID-Name, ID-Value, OL-KEY and CoverID.
title: Open Library Covers API
m: edit