Datasets API endpoint
Searches the crawled public Goodreads book catalog stored in a search index. Discovered from curated Listopia "best of" lists, a search-term sweep, and author bibliography expansion — not a full catalog. Sort enum: `relevance`, `rating_desc`, `reviews_desc`, `publication_desc`, `publication_asc`, `pages_desc`, `pages_asc`, `title_asc`. Billing: this search costs 1 credit per record returned, with a minimum of 2 (an empty result costs 2, a full page of 100 costs 100).
/datasets/goodreads-books/searchQuery parameters:
q — full-text query over title, author and description (max 256 chars).genre, format, language, publisher, author, author_id, series, isbn, isbn13, run_id — exact-match filters (max 128 chars). author matches any credited contributor (not only the primary author).min_rating (0–5), min_ratings_count, min_pages, max_pages, min_publication_year, max_publication_year — numeric filters.sort — one of relevance, rating_desc, reviews_desc, publication_desc, publication_asc, pages_desc, pages_asc, title_asc. Defaults to relevance with q, otherwise reviews_desc (popularity by ratings count).page (default 1), page_size (default 20, max 100). page * page_size must be ≤ 10000.Rows include the full author list (authors[], author_ids[]) alongside primary_author/primary_author_id, the series display string plus a filterable series_name, and the 1-5 star ratings_count distribution. Returns {dataset, items[], page, page_size, total, sort}. An empty or not-yet-populated dataset returns an empty items list, not an error.
1 credit per record returned, minimum 2. A search that returns 20 records costs 20 credits, a full page of 100 costs 100, and an empty or one-record result costs 2. You are charged for what comes back, not for the page_size you ask for, but your balance must cover the requested page_size for the call to be accepted. The response header x-credit-cost shows what a call was charged.
| Field | Filled in, of 1 checked | Values in the sample |
|---|---|---|
| id | 1 | |
| title | 1 | |
| description | 1 | median 843 characters |
| authors | 1 | median 1 entry |
| author_ids | 1 | |
| primary_author | 1 | |
| primary_author_id | 1 | |
| series | 1 | |
| series_name | 1 | |
| genres | 1 | median 10 entries |
| format | 1 | |
| pages | 1 | 374 |
| publisher | 1 | |
| publication_date | 1 | 2008-10-14 |
| publication_year | 1 | 2,008 |
| isbn | 1 | |
| isbn13 | 1 | |
| language | 1 | |
| image_url | 1 | m.media-amazon.com |
| rating_average | 1 | 4.36 |
| ratings_count | 1 | 10,306,906 |
| reviews_count | 1 | 278,675 |
| rating_one_star | 1 | 134,675 |
| rating_two_star | 1 | 243,665 |
| rating_three_star | 1 | 1,122,589 |
| rating_four_star | 1 | 3,125,853 |
| rating_five_star | 1 | 5,680,124 |
| uri | 1 | goodreads.com |
| source_url | 1 | goodreads.com |
| seed_rank | 1 | 0 |
| discovery_source | 1 | |
| run_id | 1 | |
| crawled_at | 1 | 2026-10-07 |
| schema_version | 1 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| q | string | No | Full-text query over title, author and description, max 256 characters | ||
| genre | string | No | Exact genre filter (e.g. Fantasy, Romance, Nonfiction), max 128 characters | ||
| format | string | No | Exact format filter (e.g. Hardcover, Paperback, Kindle Edition), max 128 characters | ||
| language | string | No | Exact language filter (e.g. English, Spanish), max 128 characters | ||
| publisher | string | No | Exact publisher filter, max 128 characters | ||
| author | string | No | Exact author name filter (matches any credited contributor), max 128 characters | ||
| author_id | string | No | Exact Goodreads author id filter, max 128 characters | ||
| series | string | No | Exact series name filter, max 128 characters | ||
| isbn | string | No | Exact ISBN-10 filter, max 128 characters | ||
| isbn13 | string | No | Exact ISBN-13 filter, max 128 characters | ||
| run_id | string | No | Exact crawl run-id filter, max 128 characters | ||
| min_rating | number | No | Minimum average rating, 0 through 5 | ||
| min_ratings_count | integer | No | Minimum number of ratings | ||
| min_pages | integer | No | Minimum page count | ||
| max_pages | integer | No | Maximum page count | ||
| min_publication_year | integer | No | Minimum publication year | ||
| max_publication_year | integer | No | Maximum publication year | ||
| sort | string | No | Sort enum: relevance, rating_desc, reviews_desc, publication_desc, publication_asc, pages_desc, pages_asc, title_asc Allowed values: relevance, rating_desc, reviews_desc, publication_desc, publication_asc, pages_desc, pages_asc, title_asc. | ||
| page | integer | No | 1 | Page number, defaults to 1 | |
| page_size | integer | No | 20 and maxes at 100 | Page size, defaults to 20 and maxes at 100; page * page_size must be <= 10000 | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/datasets/goodreads-books/search?q=coffee&language=en&sort=relevance&page=1" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "goodreads-books",
"items": [
{
"id": "2767052",
"title": "The Hunger Games",
"authors": [
"Suzanne Collins"
],
"author_ids": [
"153394"
],
"primary_author": "Suzanne Collins",
"primary_author_id": "153394",
"series": "The Hunger Games #1",
"series_name": "The Hunger Games",
"genres": [
"Young Adult",
"Fiction",
"Dystopia"
],
"format": "Hardcover",
"pages": 374,
"publisher": "Scholastic Press",
"publication_date": "2008-10-14",
"publication_year": 2008,
"isbn": "0439023483",
"isbn13": "9780439023481",
"language": "English",
"rating_average": 4.35,
"ratings_count": 10189669,
"reviews_count": 272857
}
],
"page": 1,
"page_size": 20,
"total": 1,
"sort": "reviews_desc"
}
}Request schema
No body schema
Response schema
#/definitions/datasets.goodreadsBooksSearchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.GoodreadsSearchResponse | No | ||||
| data.dataset | string | No | Identifier of the dataset queried (`goodreads-books`). | |||
| data.items | array | No | Matching Goodreads book records on this page. | |||
| data.items[].author_ids | array | No | Goodreads ids of the credited authors. | |||
| data.items[].authors | array | No | Authors/AuthorIDs list every credited contributor (primary + secondary); PrimaryAuthor(ID) denormalizes the first for single-value filters/facets. | |||
| data.items[].crawled_at | string | No | Time the book's data was fetched, in UTC (RFC 3339). | |||
| data.items[].description | string | No | Book description from the Goodreads page. | |||
| data.items[].discovery_source | string | No | DiscoverySource records how this id was found, e.g. "list:1", "search:mystery", "author:153394" — useful for crawl provenance/debugging. | |||
| data.items[].format | string | No | Book format, for example `Hardcover`. | |||
| data.items[].genres | array | No | List of genres Goodreads shows for the book. | |||
| data.items[].id | string | No | Goodreads book id. | |||
| data.items[].image_url | string | No | URL of the cover image. | |||
| data.items[].isbn | string | No | ISBN-10 of the edition. | |||
| data.items[].isbn13 | string | No | ISBN-13 of the edition. | |||
| data.items[].language | string | No | Language the edition is written in, for example `English`. | |||
| data.items[].pages | integer | No | Number of pages. | |||
| data.items[].primary_author | string | No | Name of the first credited author. | |||
| data.items[].primary_author_id | string | No | Goodreads id of the first credited author. | |||
| data.items[].publication_date | string | No | Publication date as Goodreads shows it, for example `2008-10-14`. | |||
| data.items[].publication_year | integer | No | Year of publication. | |||
| data.items[].publisher | string | No | Name of the book's publisher. | |||
| data.items[].rating_average | number | No | Average Goodreads rating of the book. | |||
| data.items[].rating_five_star | integer | No | Number of 5-star ratings. | |||
| data.items[].rating_four_star | integer | No | Number of 4-star ratings. | |||
| data.items[].rating_one_star | integer | No | Rating*Star is the flattened 1-5 star ratings-count distribution. | |||
| data.items[].rating_three_star | integer | No | Number of 3-star ratings. | |||
| data.items[].rating_two_star | integer | No | Number of 2-star ratings. | |||
| data.items[].ratings_count | integer | No | Number of ratings the book has received. | |||
| data.items[].reviews_count | integer | No | Number of reviews the book has received. | |||
| data.items[].run_id | string | No | Identifier of the collection run that produced this record. Accepted as a `run_id` filter. | |||
| data.items[].schema_version | integer | No | Version of the record layout. | |||
| data.items[].seed_rank | integer | No | SeedRank is the discovery priority (lower = discovered earlier/higher priority): curated list/search seeds rank low; BFS-discovered books from author expansion rank higher so curated breadth crawls first. | |||
| data.items[].series | string | No | Series is the display string (e.g. "The Hunger Games #1"); SeriesName is the bare series title, split out for exact filtering/faceting. | |||
| data.items[].series_name | string | No | Title of the series the book belongs to, without the book number. | |||
| data.items[].source_url | string | No | URL the data was read from. | |||
| data.items[].title | string | No | Title of the book. | |||
| data.items[].uri | string | No | Link to the book's Goodreads page. | |||
| data.page | integer | No | Page number returned. | |||
| data.page_size | integer | No | Number of items per page. | |||
| data.sort | string | No | Sort order applied. | |||
| data.total | integer | No | Total number of records matching the filters. | |||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/datasets/goodreads-books/search?q=coffee&language=en&sort=relevance&page=1" \
-H "x-api-key: $CRAWLORA_API_KEY"