It looks like you're offline.
Donate
English
Open Library logo

Open Library Covers API → Diff

Added
Modified
Removed
Not changed
Revision 21 by Anand Chitipothu April 14, 2011
Revision 35 by Charles Horn August 13, 2024
body
0 Our Covers API provides a programmatic method to access the book covers and author photos available in the Open Library Covers Repository. 0 Our Covers API provides a programmatic method to access the book covers and author photos available in the Open Library Covers Repository.
1 1
2 <h2>Guidelines for Cover Use</h2> 2 <h2>Guidelines for Cover Use</h2>
3 3
4 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. 4 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.
5 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="http://covers.openlibrary.org/b/isbn/9780385533225-S.jpg" />` 5 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" />`
6 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 `http://openlibrary.org/isbn/9780385533225`), or on your About page or in your footer. 6 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.
7 7
8 Thanks! 8 Thanks!
9 9
10 <h2>How To</h2> 10 <h2>How To</h2>
11 11
12 Book covers can be accessed using ID (internal cover ID), OLID (Open Library ID), ISBN, OCLC, LCCN and other identifiers like librarything and goodreads. 12 Book covers can be accessed using Cover ID (internal cover ID), OLID (Open Library ID), ISBN, OCLC, and LCCN.
13 13
14 The covers are available in 3 sizes: 14 The covers are available in 3 sizes:
15 15
16 1. <b>S</b>: Small, suitable for use as a thumbnail on a <a href="http://openlibrary.org/search?q=search+results">results page</a> on Open Library, 16 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,
17 2. <b>M</b>: Medium, suitable for display on a <a href="http://openlibrary.org/books/OL5218962M">details page</a> on Open Library and, 17 2. <b>M</b>: Medium, suitable for display on a <a href="https://openlibrary.org/books/OL5218962M">details page</a> on Open Library and,
18 3. <b>L</b>: Large 18 3. <b>L</b>: Large
19 19
20 The URL pattern to access book covers is: 20 The URL pattern to access book covers is:
21 21
22 `http://covers.openlibrary.org/b/$key/$value-$size.jpg` 22 `https://covers.openlibrary.org/b/$key/$value-$size.jpg`
23 23
24 Where: 24 Where:
25 25
26 - `key` can be any one of ISBN, OLCC, LCCN, OLID and ID (case-insensitive) 26 - `key` can be any one of ISBN, OCLC, LCCN, OLID and ID (case-insensitive)
27 - `value` is the value of the chosen key 27 - `value` is the value of the chosen key
... ...
33 33
34 <a href="http://covers.openlibrary.org/b/isbn/0385472579-S.jpg">http://covers.openlibrary.org/b/isbn/0385472579-S.jpg</a> 34 <a href="https://covers.openlibrary.org/b/isbn/0385472579-S.jpg">https://covers.openlibrary.org/b/isbn/0385472579-S.jpg</a>
35 35
36 The same cover can be accessed in multiple ways using different keys: 36 The same cover can be accessed in multiple ways using different keys:
37 37
38 <img src="http://covers.openlibrary.org/b/isbn/0385472579-S.jpg" /><br /> 38 <img src="https://covers.openlibrary.org/b/isbn/0385472579-S.jpg" /><br />
39 39
40 - http://covers.openlibrary.org/b/id/240727-S.jpg 40 - https://covers.openlibrary.org/b/id/240727-S.jpg
41 - http://covers.openlibrary.org/b/olid/OL7440033M-S.jpg 41 - https://covers.openlibrary.org/b/olid/OL7440033M-S.jpg
42 - http://covers.openlibrary.org/b/isbn/0385472579-S.jpg 42 - https://covers.openlibrary.org/b/isbn/0385472579-S.jpg
43 - http://covers.openlibrary.org/b/isbn/9780385472579-S.jpg 43 - https://covers.openlibrary.org/b/isbn/9780385472579-S.jpg
44 - http://covers.openlibrary.org/b/lccn/93005405-S.jpg 44 - https://covers.openlibrary.org/b/lccn/93005405-S.jpg
45 - http://covers.openlibrary.org/b/oclc/28419896-S.jpg 45 - https://covers.openlibrary.org/b/oclc/28419896-S.jpg
46 - http://covers.openlibrary.org/b/goodreads/979250-S.jpg
47 - http://covers.openlibrary.org/b/librarything/192819-S.jpg
48 48
... ...
54 54
55 `http://covers.openlibrary.org/a/$key/$value-$size.jpg` 53 `https://covers.openlibrary.org/a/$key/$value-$size.jpg`
56 54
57 For example the following is the photograph of <a href="http://openlibrary.org/a/OL229501A">Donald E. Knuth</a> from the Open Library. 55 For example the following is the photograph of <a href="https://openlibrary.org/a/OL229501A">Donald E. Knuth</a> from the Open Library.
58 56
59 <img src="http://covers.openlibrary.org/a/id/3365456-S.jpg" /> 57 <img src="https://covers.openlibrary.org/a/id/3365456-S.jpg" />
60 58
61   * http://covers.openlibrary.org/a/olid/OL229501A-S.jpg 59   * https://covers.openlibrary.org/a/olid/OL229501A-S.jpg
62 60
61  [1]: https://www.archive.org/details/covers_0005
62  
63 <a name="rate-limiting">&nbsp;</a>
63 64
64  [1]: http://www.archive.org/details/covers_0005 65 <h2>Cover Size & API Access</h2>
66
67 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`.
68
69 One can fetch the image off-screen and use it's width/height:
70
71 <pre>
72 async function fetchImage(url) {
73    const img = new Image();
74    return new Promise((res, rej) => {
75        img.onload = () => res(img);
76        img.onerror = e => rej(e);
77        img.src = url;
78    });
79 }
80
81 const img = await fetchImage('https://covers.openlibrary.org/b/id/12547191-L.jpg');
82 const w = img.width;
83 const h = img.height;
84 </pre>
85
86 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.
87
88 <h2>Rate Limiting</h2>
89
90 The cover access by ids other than CoverID and OLID are rate-limited. Currently only 100 requests/IP are allowed for every 5 minutes.
91
92 If any IP tries to access more that the allowed limit, the service will return "403 Forbidden" status.
93
94 <a name="bulk-access">&nbsp;</a>
95
96 <h2>Bulk Access</h2>
97
98 The covers API is intended for displaying covers on public facing websites and not for bulk download.
99
100 If you are interested to download the covers in bulk, please download them from:
101
102 * Small Covers:
103
104    * <https://www.archive.org/details/s_covers_0000>
105    * ...
106    * <https://www.archive.org/details/s_covers_0006>
107
108 * Medium Covers:
109
110    * <https://www.archive.org/details/m_covers_0000>
111    * ...
112    * <https://www.archive.org/details/m_covers_0006>
113
114 * Large Covers:
115
116    * <https://www.archive.org/details/l_covers_0000>
117    * ...
118    * <https://www.archive.org/details/l_covers_0006>
119
120 * Original Covers:
121
122    * <https://www.archive.org/details/covers_0000>
123    * ...
124    * <https://www.archive.org/details/covers_0005>
125    
126 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`.
127
128 The mapping from various IDs to CoverIDs is available at:
129
130 <https://www.archive.org/download/ol_dump_2011-03-31/ol_dump_coverids_2011-03-31.txt.gz>
131
132 It has 4 columns ID-Name, ID-Value, OL-KEY and CoverID.