# Goodreads Book

## Overview

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

## Description

Read one Goodreads book by the numeric id from search, such as 44767458 for Dune.

## 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/book' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Dune

```json
{
  "id": "44767458",
  "url": "https://www.goodreads.com/book/show/44767458",
  "isbn": "9780593099322",
  "image": "https://m.media-amazon.com/images/S/compressed.photo.goodreads.com/books/1555447414i/44767458.jpg",
  "pages": 658,
  "title": "Dune",
  "awards": [
    "Hugo Award Best Novel (1966)",
    "Nebula Award Best Novel (1965)",
    "Seiun Award 星雲賞 Best Foreign Novel (1974)"
  ],
  "genres": [
    "Science Fiction",
    "Fiction",
    "Fantasy",
    "Classics",
    "Audiobook",
    "Science Fiction Fantasy",
    "Space Opera"
  ],
  "rating": 4.29,
  "series": "Dune #1",
  "authors": [
    "Frank Herbert"
  ],
  "language": "English",
  "published": "June 1, 1965",
  "book_format": "Hardcover",
  "description": "Set on the desert planet Arrakis, Dune is the story of the boy Paul Atreides, heir to a noble family tasked with ruling an inhospitable world where the only thing of value is the “spice” melange, a drug capable of extending life and enhancing consciousness. Coveted across the known universe, melange is a prize worth killing for... When House Atreides is betrayed, the destruction of Paul’s family will set the boy on a journey toward a destiny greater than he could ever have imagined. And as he evolves into the mysterious man known as Muad’Dib, he will bring to fruition humankind’s most ancient and unattainable dream. Show more",
  "ratings_count": 1723657,
  "reviews_count": 90495
}
```

## Documentation

## Overview

Read one Goodreads book page. Pass the numeric id from search, or a `/book/show/` URL. The response is a flat book record. `44767458` is Dune by Frank Herbert, the same id and title as the first `dune` search card.

The search card stores an abbreviated ratings floor. This endpoint stores the exact `ratings_count` and `reviews_count` printed on the book page.

## Quickstart

```
GET https://api.piloterr.com/v2/goodreads/book?query=44767458
GET https://api.piloterr.com/v2/goodreads/book?query=https://www.goodreads.com/book/show/44767458
```

GET and POST take the same `query`. The Dune record includes ISBN `9780593099322`, `658` pages, format `Hardcover`, and series `Dune #1`.

## Parameters

| Parameter | Required | Example |
|---|---|---|
| `query` | yes | `44767458` |

`query` is required. A bare integer is the book id. A URL must be on `goodreads.com` and contain `/book/show/`. A title, a search URL, or another host returns 400.

## Response fields

| Field | Type | Meaning |
|---|---|---|
| `id` | string | Book id from the URL, such as `44767458` |
| `title` | string | Title |
| `url` | string | Canonical `/book/show/{id}` URL |
| `series` | string or null | Series link text, such as `Dune #1` |
| `authors` | array of strings | Authors. Dune lists `Frank Herbert` |
| `rating` | number or null | Average rating |
| `ratings_count` | number or null | Exact rating count from the book page |
| `reviews_count` | number or null | Exact review count |
| `image` | string or null | Cover |
| `book_format` | string or null | Format, such as `Hardcover` |
| `pages` | number or null | Page count |
| `language` | string or null | Language |
| `isbn` | string or null | ISBN |
| `genres` | array of strings | Genre buttons on the page |
| `published` | string or null | First published date when the page prints `First published ...` |
| `awards` | array | Award lines. Empty array when none are present |
| `description` | string or null | Description text, with a trailing "more" control removed |

There is no `results` wrapper. The series string on this page can differ from the search card for the same id.

## Use cases

- Store ISBN `9780593099322`, 658 pages, and Hardcover for a catalog row keyed by `44767458`.
- Keep the exact rating count from the book page after a search card stored the abbreviated floor `1700000`.
- Read genres and the Hugo and Nebula award lines printed for Dune.

## Error codes

| Code | Meaning |
|---|---|
| `400` | Empty query, a non-numeric token, or a domain outside goodreads.com |
| `401` | Missing API key |
| `404` | No book page for that id |
| `500` | The fetch failed |

## Related endpoints

[Goodreads Search](https://www.piloterr.com/library/goodreads-search)