Card type

Book search API

Books for a genre, a topic, an author, a book they should be like, or constraints (rating, years, length), with their covers, authors and ratings, and filters that say how many books each option leaves. From WebKnox's book index, built on Open Library's data; each book links to its page there, and covers are the publishers' art, shown with the card's credit. Results are in English.

Card type book.search · version 1 · schema book.search.v1.schema.json

Layouts

Every card type has full. Pick a layout with the element's layout attribute, render.layout, or a theme.

Fields

The fields of card.data. Values a source doesn't provide are null; new optional fields can appear within version 1.

Field	Type	Required	Notes
`query`	`string`	yes	What was searched for, in English, without the words the filters took ("cozy mysteries"); "like Dune" for books similar to a title. Empty when only filters were asked for.
`filters`	`object`	yes	Genres and authors: any of the chosen (or). Rating, published and length: one each. All of them together (and).
`filters.genres[]`	`string[]`	yes	Genres (fantasy, science_fiction, mystery, …), any of them.
`filters.authors[]`	`string[]`	yes	Authors by the slug of their name, any of them. One word is a surname (tolkien).
`filters.rating`	`enum`	yes	At least this many stars out of 5, from at least 10 ratings. · 3.5 · 4 · 4.5
`filters.published`	`object`	yes	Published from min to max (years; either may be null). Books without a year are left out while either is set.
`filters.published.min`	`integer \| null`	yes
`filters.published.max`	`integer \| null`	yes
`filters.length`	`enum`	yes	short: under 200 pages; medium: 200 to 400; long: over 400. Books without a page count are left out while it is set. · short · medium · long
`sort`	`enum`	yes	match: best match first; rating: highest rated first, books with fewer than 10 ratings last; popular: most ratings first; newest, oldest: by year, books without a year last. match · rating · popular · newest · oldest
`total`	`integer`	yes	How many books match, of which results holds the first limit.
`capped`	`boolean`	yes	true when the search looked only at the 1,000 best candidates of the index: total and the counts are over those of them that pass the filters, and more may match (show the total with a "+").
`limit`	`integer`	yes	How many results were asked for: 24, or more after a refine asked for more.
`results[]`	`object[]`	yes
`results[].id`	`integer`	yes	The book index's id for the book.
`results[].title`	`string`	yes
`results[].subtitle`	`string \| null`	yes
`results[].cover_url`	`url \| null`	yes	WebKnox media URL of the cover (taller than wide), or null when none is known.
`results[].authors[]`	`string[]`	yes
`results[].year`	`integer \| null`	yes	When it was published, as far as known: often the edition's year, not the first.
`results[].pages`	`integer \| null`	yes
`results[].rating`	`number \| null`	yes	Average rating out of 5, one decimal, or null when not rated.
`results[].rating_count`	`integer \| null`	yes	How many ratings it is based on.
`results[].genres[]`	`string[]`	yes
`results[].description`	`string \| null`	yes	A few sentences about it, shortened, or null.
`results[].url`	`url \| null`	yes	The book's page at Open Library.
`facets`	`object`	yes	For every option: how many books there would be with it alone chosen in its section and every other section's filters as they are. Genres and authors: the most common ones among the books, most first, the chosen ones always included.
`facets.genres[]`	`object[]`	yes	By genre.
`facets.genres[].value`	`string`	yes	A genre (science_fiction, mystery) or an author's name as a slug (stephen_king, jrr_tolkien).
`facets.genres[].label`	`string`	yes
`facets.genres[].count`	`integer`	yes
`facets.authors[]`	`object[]`	yes	By author.
`facets.authors[].value`	`string`	yes	A genre (science_fiction, mystery) or an author's name as a slug (stephen_king, jrr_tolkien).
`facets.authors[].label`	`string`	yes
`facets.authors[].count`	`integer`	yes
`facets.rating`	`object`	yes	By minimum rating.
`facets.rating.4`	`integer`
`facets.rating.3.5`	`integer`
`facets.rating.4.5`	`integer`
`facets.published`	`null \| object`	yes
`facets.published.min`	`integer`	yes
`facets.published.max`	`integer`	yes
`facets.published.bins[]`	`integer[]`	yes
`facets.length`	`object`	yes	By length.
`facets.length.short`	`integer`
`facets.length.medium`	`integer`
`facets.length.long`	`integer`
`relax[]`	`object[]`	yes	Only when nothing matches: applied filters that, dropped alone, bring books back, with how many. Empty otherwise.
`relax[].filter`	`object`	yes	One applied filter: a genre or author with its value, or the rating, published or length (value null).
`relax[].filter.kind`	`enum`	yes	genre · author · rating · published · length
`relax[].filter.value`	`string \| null`	yes
`relax[].count`	`integer`	yes
`credit`	`string`	yes	Where the books and covers come from. Show it with the results.

Example

A recorded answer to “Cozy mysteries”. Open it in the Answer Lab to see every layout and style.

Response

1{
2  "v": 2,
3  "id": "ans_q1k86b9fakrrlrds",
4  "matched": true,
5  "locale": "en",
6  "skill": "book_search",
7  "confidence": 0.9,
8  "text": "19 books for cozy mysteries. The best matches: Chocolate Chip Cookie Murder (Joanne Fluke, 2000); Aunt Dimity's Death (Nancy Atherton, 1992); Sugar Cookie Murder (Joanne Fluke, 2004); Key Lime Pie Murder (Joanne Fluke, 2007); Death at Wentwater Court (Carola Dunn, 1994).",
9  "speech": "I found 19 books for cozy mysteries. The first is Chocolate Chip Cookie Murder by Joanne Fluke.",
10  "card": {
11    "type": "book.search",
12    "version": 1,
13    "data": {
14      "query": "cozy mysteries",
15      "filters": {
16        "genres": [],
17        "authors": [],
18        "rating": null,
19        "published": {
20          "min": null,
21          "max": null
22        },
23        "length": null
24      },
25      "sort": "match",
26      "total": 19,
27      "capped": false,
28      "limit": 24,
29      "results": [
30        {
31          "id": 515898,
32          "title": "Chocolate Chip Cookie Murder",
33          "subtitle": null,
34          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/7401253-L.jpg",
35          "authors": [
36            "Joanne Fluke"
37          ],
38          "year": 2000,
39          "pages": 340,
40          "rating": 3.7,
41          "rating_count": 41200,
42          "genres": [
43            "Mystery",
44            "Fiction"
45          ],
46          "description": "Bakery owner Hannah Swensen finds a deliveryman dead behind her cookie shop in small-town Minnesota and starts asking questions.",
47          "url": "https://openlibrary.org/works/OL515898W"
48        },
49        {
50          "id": 14949603,
51          "title": "Aunt Dimity's Death",
52          "subtitle": null,
53          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/10020476-L.jpg",
54          "authors": [
55            "Nancy Atherton"
56          ],
57          "year": 1992,
58          "pages": 256,
59          "rating": 4,
60          "rating_count": 14300,
61          "genres": [
62            "Mystery",
63            "Paranormal",
64            "Fiction"
65          ],
66          "description": "A quiet Boston secretary inherits a cottage in the Cotswolds from a woman she thought was only a bedtime story, along with a friendly ghost.",
67          "url": "https://openlibrary.org/works/OL14949603W"
68        },
69        {
70          "id": 21183325,
71          "title": "Sugar Cookie Murder",
72          "subtitle": null,
73          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/13108339-L.jpg",
74          "authors": [
75            "Joanne Fluke"
76          ],
77          "year": 2004,
78          "pages": 336,
79          "rating": 3.8,
80          "rating_count": 9800,
81          "genres": [
82            "Mystery",
83            "Fiction"
84          ],
85          "description": null,
86          "url": "https://openlibrary.org/works/OL21183325W"
87        },
88        {
89          "id": 515925,
90          "title": "Key Lime Pie Murder",
91          "subtitle": null,
92          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/1416795-L.jpg",
93          "authors": [
94            "Joanne Fluke"
95          ],
96          "year": 2007,
97          "pages": 357,
98          "rating": 3.9,
99          "rating_count": 8900,
100          "genres": [
101            "Mystery",
102            "Fiction"
103          ],
104          "description": null,
105          "url": "https://openlibrary.org/works/OL515925W"
106        },
107        {
108          "id": 20885652,
109          "title": "Death at Wentwater Court",
110          "subtitle": null,
111          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/10213060-L.jpg",
112          "authors": [
113            "Carola Dunn"
114          ],
115          "year": 1994,
116          "pages": 250,
117          "rating": 3.7,
118          "rating_count": 6100,
119          "genres": [
120            "Mystery",
121            "Historical fiction",
122            "Fiction"
123          ],
124          "description": "A young journalist in 1920s England goes to a country house to write about it and finds a guest dead on the ice.",
125          "url": "https://openlibrary.org/works/OL20885652W"
126        },
127        {
128          "id": 15951438,
129          "title": "As the Pig Turns",
130          "subtitle": null,
131          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/8239002-L.jpg",
132          "authors": [
133            "M. C. Beaton"
134          ],
135          "year": 2011,
136          "pages": 292,
137          "rating": 3.7,
138          "rating_count": 5200,
139          "genres": [
140            "Mystery",
141            "Fiction"
142          ],
143          "description": null,
144          "url": "https://openlibrary.org/works/OL15951438W"
145        },
146        {
147          "id": 1985111,
148          "title": "Murder with Puffins",
149          "subtitle": null,
150          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/14598684-L.jpg",
151          "authors": [
152            "Donna Andrews"
153          ],
154          "year": 2000,
155          "pages": 308,
156          "rating": 3.8,
157          "rating_count": 5600,
158          "genres": [
159            "Mystery",
160            "Humor",
161            "Fiction"
162          ],
163          "description": "A getaway to a remote Maine island with her boyfriend turns into a murder investigation for blacksmith Meg Langslow, and a hunt among the puffin watchers.",
164          "url": "https://openlibrary.org/works/OL1985111W"
165        },
166        {
167          "id": 17316,
168          "title": "The Winter Garden Mystery",
169          "subtitle": null,
170          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/829126-L.jpg",
171          "authors": [
172            "Carola Dunn"
173          ],
174          "year": 1995,
175          "pages": 256,
176          "rating": 3.8,
177          "rating_count": 3200,
178          "genres": [
179            "Mystery",
180            "Historical fiction",
181            "Fiction"
182          ],
183          "description": null,
184          "url": "https://openlibrary.org/works/OL17316W"
185        },
186        {
187          "id": 20853633,
188          "title": "Agatha Raisin and the Blood of an Englishman",
189          "subtitle": null,
190          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/10166188-L.jpg",
191          "authors": [
192            "M. C. Beaton"
193          ],
194          "year": 2014,
195          "pages": 232,
196          "rating": 3.7,
197          "rating_count": 4100,
198          "genres": [
199            "Mystery",
200            "Fiction"
201          ],
202          "description": null,
203          "url": "https://openlibrary.org/works/OL20853633W"
204        },
205        {
206          "id": 20032918,
207          "title": "Pushing Up Daisies",
208          "subtitle": null,
209          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/13084796-L.jpg",
210          "authors": [
211            "M. C. Beaton"
212          ],
213          "year": 2016,
214          "pages": 280,
215          "rating": 3.6,
216          "rating_count": 2900,
217          "genres": [
218            "Mystery",
219            "Fiction"
220          ],
221          "description": null,
222          "url": "https://openlibrary.org/works/OL20032918W"
223        },
224        {
225          "id": 14911361,
226          "title": "Double Shot",
227          "subtitle": null,
228          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/27482-L.jpg",
229          "authors": [
230            "Diane Mott Davidson"
231          ],
232          "year": 2004,
233          "pages": 400,
234          "rating": 4,
235          "rating_count": 3900,
236          "genres": [
237            "Mystery",
238            "Fiction"
239          ],
240          "description": null,
241          "url": "https://openlibrary.org/works/OL14911361W"
242        },
243        {
244          "id": 529879,
245          "title": "Mail-Order Murder",
246          "subtitle": null,
247          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/9552301-L.jpg",
248          "authors": [
249            "Leslie Meier"
250          ],
251          "year": 1991,
252          "pages": null,
253          "rating": 3.6,
254          "rating_count": 3100,
255          "genres": [
256            "Mystery",
257            "Fiction"
258          ],
259          "description": null,
260          "url": "https://openlibrary.org/works/OL529879W"
261        },
262        {
263          "id": 27876,
264          "title": "Mrs. Pollifax on the China Station",
265          "subtitle": null,
266          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/10649226-L.jpg",
267          "authors": [
268            "Dorothy Gilman"
269          ],
270          "year": 1983,
271          "pages": 184,
272          "rating": 4.1,
273          "rating_count": 2400,
274          "genres": [
275            "Mystery",
276            "Fiction"
277          ],
278          "description": null,
279          "url": "https://openlibrary.org/works/OL27876W"
280        },
281        {
282          "id": 515920,
283          "title": "Cream Puff Murder",
284          "subtitle": null,
285          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/7401205-L.jpg",
286          "authors": [
287            "Joanne Fluke"
288          ],
289          "year": 2009,
290          "pages": 469,
291          "rating": 3.8,
292          "rating_count": 8100,
293          "genres": [
294            "Mystery",
295            "Romance",
296            "Fiction"
297          ],
298          "description": null,
299          "url": "https://openlibrary.org/works/OL515920W"
300        },
301        {
302          "id": 21675300,
303          "title": "Death of a Charming Man",
304          "subtitle": null,
305          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/10393048-L.jpg",
306          "authors": [
307            "M. C. Beaton"
308          ],
309          "year": 1994,
310          "pages": 276,
311          "rating": 3.8,
312          "rating_count": 4600,
313          "genres": [
314            "Mystery",
315            "Fiction"
316          ],
317          "description": null,
318          "url": "https://openlibrary.org/works/OL21675300W"
319        },
320        {
321          "id": 21891560,
322          "title": "Christmas Cupcake Murder",
323          "subtitle": null,
324          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/10886869-L.jpg",
325          "authors": [
326            "Joanne Fluke"
327          ],
328          "year": 2020,
329          "pages": 288,
330          "rating": 3.5,
331          "rating_count": 2100,
332          "genres": [
333            "Mystery",
334            "Fiction"
335          ],
336          "description": null,
337          "url": "https://openlibrary.org/works/OL21891560W"
338        },
339        {
340          "id": 24259726,
341          "title": "Death of a Gentle Lady",
342          "subtitle": null,
343          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/10746953-L.jpg",
344          "authors": [
345            "M. C. Beaton"
346          ],
347          "year": 2008,
348          "pages": 312,
349          "rating": 3.8,
350          "rating_count": 3800,
351          "genres": [
352            "Mystery",
353            "Fiction"
354          ],
355          "description": null,
356          "url": "https://openlibrary.org/works/OL24259726W"
357        },
358        {
359          "id": 22436551,
360          "title": "Triple Chocolate Cheesecake Murder",
361          "subtitle": null,
362          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/10459714-L.jpg",
363          "authors": [
364            "Joanne Fluke"
365          ],
366          "year": 2021,
367          "pages": 304,
368          "rating": 3.5,
369          "rating_count": 1700,
370          "genres": [
371            "Mystery",
372            "Fiction"
373          ],
374          "description": null,
375          "url": "https://openlibrary.org/works/OL22436551W"
376        },
377        {
378          "id": 15602951,
379          "title": "A Highland Christmas",
380          "subtitle": null,
381          "cover_url": "https://webknox.com/media/v1/covers.openlibrary.org/b/id/10967568-L.jpg",
382          "authors": [
383            "M. C. Beaton"
384          ],
385          "year": 1999,
386          "pages": 144,
387          "rating": 3.9,
388          "rating_count": 3300,
389          "genres": [
390            "Mystery",
391            "Fiction"
392          ],
393          "description": null,
394          "url": "https://openlibrary.org/works/OL15602951W"
395        }
396      ],
397      "facets": {
398        "genres": [
399          {
400            "value": "fiction",
401            "label": "Fiction",
402            "count": 19
403          },
404          {
405            "value": "mystery",
406            "label": "Mystery",
407            "count": 19
408          },
409          {
410            "value": "historical_fiction",
411            "label": "Historical fiction",
412            "count": 2
413          },
414          {
415            "value": "humor",
416            "label": "Humor",
417            "count": 1
418          },
419          {
420            "value": "paranormal",
421            "label": "Paranormal",
422            "count": 1
423          },
424          {
425            "value": "romance",
426            "label": "Romance",
427            "count": 1
428          }
429        ],
430        "authors": [
431          {
432            "value": "joanne_fluke",
433            "label": "Joanne Fluke",
434            "count": 6
435          },
436          {
437            "value": "mc_beaton",
438            "label": "M. C. Beaton",
439            "count": 6
440          },
441          {
442            "value": "carola_dunn",
443            "label": "Carola Dunn",
444            "count": 2
445          },
446          {
447            "value": "diane_mott_davidson",
448            "label": "Diane Mott Davidson",
449            "count": 1
450          },
451          {
452            "value": "donna_andrews",
453            "label": "Donna Andrews",
454            "count": 1
455          },
456          {
457            "value": "dorothy_gilman",
458            "label": "Dorothy Gilman",
459            "count": 1
460          },
461          {
462            "value": "leslie_meier",
463            "label": "Leslie Meier",
464            "count": 1
465          },
466          {
467            "value": "nancy_atherton",
468            "label": "Nancy Atherton",
469            "count": 1
470          }
471        ],
472        "rating": {
473          "4": 3,
474          "3.5": 19,
475          "4.5": 0
476        },
477        "published": {
478          "min": 1983,
479          "max": 2021,
480          "bins": [
481            1,
482            0,
483            1,
484            3,
485            1,
486            1,
487            2,
488            2,
489            2,
490            1,
491            1,
492            2,
493            0,
494            2
495          ]
496        },
497        "length": {
498          "short": 2,
499          "medium": 15,
500          "long": 1
501        }
502      },
503      "relax": [],
504      "credit": "Books and covers: Open Library. Cover art: the books' publishers."
505    }
506  },
507  "sources": [
508    {
509      "name": "Open Library",
510      "url": "https://openlibrary.org",
511      "license": null
512    }
513  ],
514  "follow_ups": [],
515  "actions": [],
516  "usage": {
517    "billable": true
518  }
519}

Book search API

Layouts

Fields

Example

Related cards