# Goodreads Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/goodreads/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/goodreads-search |

## Description

Search Goodreads books by keyword. pagination.next is a Goodreads search URL for the following page.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/goodreads/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Dune

```json
{
  "results": [
    {
      "id": "44767458",
      "url": "https://www.goodreads.com/book/show/44767458",
      "image": "https://m.media-amazon.com/images/S/compressed.photo.goodreads.com/books/1555447414i/44767458.jpg",
      "title": "Dune",
      "rating": 4.29,
      "series": "Dune (Series #1)",
      "authors": [
        "Frank Herbert"
      ],
      "ratings_count": 1700000,
      "reviews_count": 90400
    }
  ],
  "pagination": {
    "next": "https://www.goodreads.com/search?q=dune&page=2",
    "page": 1,
    "per_page": 20,
    "total_pages": 100,
    "total_results": null
  }
}
```

## Documentation

## Overview

Search books on Goodreads. Send a keyword such as `dune` or `pride and prejudice`, and an optional page. The response is `{ results, pagination }`. Each card has a numeric Goodreads id. Pass that id to `/v2/goodreads/book`. For Dune the id is `44767458`.

Ratings on a search card can be abbreviated. A label such as `1.7 million ratings` is stored as `1700000`. The book endpoint returns the exact count from the book page.

## Quickstart

GET and POST take the same parameters.

```
GET https://api.piloterr.com/v2/goodreads/search?query=dune
GET https://api.piloterr.com/v2/goodreads/search?query=dune&page=2
GET https://api.piloterr.com/v2/goodreads/search?query=https://www.goodreads.com/search?q=dune&page=2
```

Page 1 of `dune` includes `44767458` / `Dune` by Frank Herbert. `pagination.next` is `https://www.goodreads.com/search?q=dune&page=2`. Page 2 uses that URL, reports `pagination.page` `2`, and its book ids do not repeat page 1. Its `next` is the page 3 Goodreads URL.

## Parameters

| Parameter | Required | Example |
|---|---|---|
| `query` | yes | `dune` |
| `page` | no | `2` |

`query` is required. A Goodreads URL must be a search URL. Another host returns 400. `page` is optional and defaults to 1. It must be an integer of at least 1. When both a search URL and `page` are sent, `page` overwrites the page in the URL.

## Pagination

`pagination.page` is the page Goodreads prints (`Page N of M`) or, if that label is missing, the `page` query value. `pagination.total_pages` is the `M` from that label, for example `100` on `dune`. `pagination.total_results` is `null` because the search page does not print a result total. `pagination.per_page` is the number of book cards parsed, `20` on a full `dune` page.

`pagination.next` is the Goodreads URL of the Next link, such as `https://www.goodreads.com/search?q=dune&page=2`. It is `null` only when that link is absent, which is the last page. Follow `next`, or send the same keyword with `page` set to the next number. Ids are unique on a page, and a later page does not repeat them.

## Response fields

| Field | Type | Meaning |
|---|---|---|
| `results[].id` | string | Numeric Goodreads book id, such as `44767458` |
| `results[].title` | string | Title |
| `results[].url` | string | `https://www.goodreads.com/book/show/{id}` |
| `results[].series` | string or null | Series label from the card, such as `Dune (Series #1)` |
| `results[].authors` | array of strings | Author names |
| `results[].rating` | number or null | Average rating |
| `results[].ratings_count` | number or null | Ratings. Abbreviated labels use the displayed floor, so `1.7 million` becomes `1700000` |
| `results[].reviews_count` | number or null | Reviews, with the same abbreviation rule |
| `results[].image` | string or null | Cover URL |
| `pagination.page` | integer | Current page |
| `pagination.per_page` | integer or null | Cards on this page |
| `pagination.total_results` | null | Not printed |
| `pagination.total_pages` | integer or null | Page count Goodreads prints |
| `pagination.next` | string or null | Next Goodreads search URL |

The book page for `44767458` uses the same id and title. Its series label can differ slightly (`Dune #1` on the book page, `Dune (Series #1)` on the card) because the two pages print different strings.

## Use cases

- Resolve the title Dune to id `44767458` before reading ISBN, page count, and the exact rating total.
- Walk `pagination.next` for `dune` and collect author names without repeating ids from page 1.
- Compare abbreviated card ratings for `pride and prejudice` on page 1, then open the book endpoint for the exact count.

## Error codes

| Code | Meaning |
|---|---|
| `400` | Empty query, a page below 1, or a domain outside goodreads.com |
| `401` | Missing API key |
| `404` | The page was not a book search |
| `500` | The fetch failed |

## Related endpoints

[Goodreads Book](https://www.piloterr.com/library/goodreads-book)