---
title: "Search Goodreads books dataset"
method: GET
path: "/datasets/goodreads-books/search"
tags: ["Datasets"]
---

# Search Goodreads books dataset

`GET /datasets/goodreads-books/search`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/datasets/goodreads-books/search`
- Auth: API key in header `x-api-key`

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).

## Query parameters

- `q` string
- `genre` string
- `format` string
- `language` string
- `publisher` string
- `author` string
- `author_id` string
- `series` string
- `isbn` string
- `isbn13` string
- `run_id` string
- `min_rating` number
- `min_ratings_count` integer
- `min_pages` integer
- `max_pages` integer
- `min_publication_year` integer
- `max_publication_year` integer
- `sort` 'relevance' | 'rating_desc' | 'reviews_desc' | 'publication_desc' | 'publication_asc' | 'pages_desc' | 'pages_asc' | 'title_asc'
- `page` integer
- `page_size` integer

## Headers

- `x-api-key` string, required

## Response `200`

OK

- DatasetsGoodreadsBooksSearchResponseDoc
  - `code` integer
  - `data` DatasetsGoodreadsSearchResponse
    - `dataset` string: Identifier of the dataset queried (`goodreads-books`).
    - `items` EsGoodreadsBookRecord[]: Matching Goodreads book records on this page.
      - `author_ids` string[]: Goodreads ids of the credited authors.
      - `authors` string[]: Authors/AuthorIDs list every credited contributor (primary + secondary); PrimaryAuthor(ID) denormalizes the first for single-value filters/facets.
      - `crawled_at` string: Time the book's data was fetched, in UTC (RFC 3339).
      - `description` string: Book description from the Goodreads page.
      - `discovery_source` string: DiscoverySource records how this id was found, e.g. "list:1", "search:mystery", "author:153394" — useful for crawl provenance/debugging.
      - `format` string: Book format, for example `Hardcover`.
      - `genres` string[]: List of genres Goodreads shows for the book.
      - `id` string: Goodreads book id.
      - `image_url` string: URL of the cover image.
      - `isbn` string: ISBN-10 of the edition.
      - `isbn13` string: ISBN-13 of the edition.
      - `language` string: Language the edition is written in, for example `English`.
      - `pages` integer: Number of pages.
      - `primary_author` string: Name of the first credited author.
      - `primary_author_id` string: Goodreads id of the first credited author.
      - `publication_date` string: Publication date as Goodreads shows it, for example `2008-10-14`.
      - `publication_year` integer: Year of publication.
      - `publisher` string: Name of the book's publisher.
      - `rating_average` number: Average Goodreads rating of the book.
      - `rating_five_star` integer: Number of 5-star ratings.
      - `rating_four_star` integer: Number of 4-star ratings.
      - `rating_one_star` integer: Rating*Star is the flattened 1-5 star ratings-count distribution.
      - `rating_three_star` integer: Number of 3-star ratings.
      - `rating_two_star` integer: Number of 2-star ratings.
      - `ratings_count` integer: Number of ratings the book has received.
      - `reviews_count` integer: Number of reviews the book has received.
      - `run_id` string: Identifier of the collection run that produced this record. Accepted as a `run_id` filter.
      - `schema_version` integer: Version of the record layout.
      - `seed_rank` integer: 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.
      - `series` string: Series is the display string (e.g. "The Hunger Games #1"); SeriesName is the bare series title, split out for exact filtering/faceting.
      - `series_name` string: Title of the series the book belongs to, without the book number.
      - `source_url` string: URL the data was read from.
      - `title` string: Title of the book.
      - `uri` string: Link to the book's Goodreads page.
    - `page` integer: Page number returned.
    - `page_size` integer: Number of items per page.
    - `sort` string: Sort order applied.
    - `total` integer: Total number of records matching the filters.
  - `msg` string

## Other responses

- `400`: Bad Request
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/afac9b012a27?raw)