Piloterr Goodreads API
The Goodreads API from Piloterr — 2 operation(s) for goodreads.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/piloterr-com:piloterr-com-goodreads-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Piloterr API Reference Goodreads API
description: Complete API reference documentation.
version: 1.0.0
servers:
- url: https://api.piloterr.com
description: API Server
tags:
- name: Goodreads
paths:
/v2/goodreads/book:
get:
summary: Goodreads Book
description: 'Read one Goodreads book by the numeric id from search, such as 44767458 for Dune.
**Credit cost:** 2 credits per call'
operationId: get-goodreads-book
security:
- ApiKeyAuth: []
parameters:
- name: query
in: query
required: true
description: 'Required. The numeric Goodreads book id from search, or a /book/show/ URL. A title is not accepted.
**Example:**
```
44767458
```
**URL example:**
```
https://www.goodreads.com/book/show/44767458
```'
schema:
type: string
description: 'Required. The numeric Goodreads book id from search, or a /book/show/ URL. A title is not accepted.
**Example:**
```
44767458
```
**URL example:**
```
https://www.goodreads.com/book/show/44767458
```'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/is_async'
- $ref: '#/components/parameters/soft_fail'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
id:
type: string
url:
type: string
isbn:
type: string
image:
type: string
pages:
type: integer
title:
type: string
awards:
type: array
items:
type: string
genres:
type: array
items:
type: string
rating:
type: number
series:
type: string
authors:
type: array
items:
type: string
language:
type: string
published:
type: string
book_format:
type: string
description:
type: string
ratings_count:
type: integer
reviews_count:
type: integer
examples:
Dune:
value:
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
'400':
description: Bad Request — missing or invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
'401':
description: Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidKey:
value:
error: Invalid API Key
planRateLimit:
value:
error: 'Rate limit exceeded: You''ve exceeded the per second rate limit on your subscription'
keyQuota:
value:
error: 'Rate limit exceeded for the API key: quota monthly'
'402':
description: Payment Required — your subscription or credit balance is insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Payment required
'500':
description: Internal Server Error — something went wrong on our side.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Error
tags:
- Goodreads
post:
summary: Goodreads Book
description: 'Read one Goodreads book by the numeric id from search, such as 44767458 for Dune.
**Credit cost:** 2 credits per call'
operationId: post-goodreads-book
security:
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/is_async'
- $ref: '#/components/parameters/soft_fail'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
query:
type: string
description: 'Required. The numeric Goodreads book id from search, or a /book/show/ URL. A title is not accepted.
**Example:**
```
44767458
```
**URL example:**
```
https://www.goodreads.com/book/show/44767458
```'
required:
- query
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
id:
type: string
url:
type: string
isbn:
type: string
image:
type: string
pages:
type: integer
title:
type: string
awards:
type: array
items:
type: string
genres:
type: array
items:
type: string
rating:
type: number
series:
type: string
authors:
type: array
items:
type: string
language:
type: string
published:
type: string
book_format:
type: string
description:
type: string
ratings_count:
type: integer
reviews_count:
type: integer
examples:
Dune:
value:
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
'400':
description: Bad Request — missing or invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
'401':
description: Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidKey:
value:
error: Invalid API Key
planRateLimit:
value:
error: 'Rate limit exceeded: You''ve exceeded the per second rate limit on your subscription'
keyQuota:
value:
error: 'Rate limit exceeded for the API key: quota monthly'
'402':
description: Payment Required — your subscription or credit balance is insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Payment required
'500':
description: Internal Server Error — something went wrong on our side.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Error
tags:
- Goodreads
/v2/goodreads/search:
get:
summary: Goodreads Search
description: 'Search Goodreads books by keyword. pagination.next is a Goodreads search URL for the following page.
**Credit cost:** 2 credits per call'
operationId: get-goodreads-search
security:
- ApiKeyAuth: []
parameters:
- name: query
in: query
required: true
description: 'Required. A book keyword, or a Goodreads search URL (the path contains /search or the query contains q=).
**Example:**
```
dune
```
**URL example:**
```
https://www.goodreads.com/search?q=dune&page=2
```'
schema:
type: string
description: 'Required. A book keyword, or a Goodreads search URL (the path contains /search or the query contains q=).
**Example:**
```
dune
```
**URL example:**
```
https://www.goodreads.com/search?q=dune&page=2
```'
- name: page
in: query
required: false
description: 'Optional. Page number, starting at 1. Omitted or blank uses page 1. A value below 1 returns 400. When query is already a Goodreads search URL, this number replaces the page parameter in that URL.
**Example:**
```
2
```'
schema:
type: number
default: '1'
description: 'Optional. Page number, starting at 1. Omitted or blank uses page 1. A value below 1 returns 400. When query is already a Goodreads search URL, this number replaces the page parameter in that URL.
**Example:**
```
2
```'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/is_async'
- $ref: '#/components/parameters/soft_fail'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
type: object
properties:
id:
type: string
url:
type: string
image:
type: string
title:
type: string
rating:
type: number
series:
type: string
authors:
type: array
items:
type: string
ratings_count:
type: integer
reviews_count:
type: integer
pagination:
type: object
properties:
next:
type: string
page:
type: integer
per_page:
type: integer
total_pages:
type: integer
total_results:
nullable: true
examples:
Dune:
value:
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
'400':
description: Bad Request — missing or invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
'401':
description: Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidKey:
value:
error: Invalid API Key
planRateLimit:
value:
error: 'Rate limit exceeded: You''ve exceeded the per second rate limit on your subscription'
keyQuota:
value:
error: 'Rate limit exceeded for the API key: quota monthly'
'402':
description: Payment Required — your subscription or credit balance is insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Payment required
'500':
description: Internal Server Error — something went wrong on our side.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Error
tags:
- Goodreads
post:
summary: Goodreads Search
description: 'Search Goodreads books by keyword. pagination.next is a Goodreads search URL for the following page.
**Credit cost:** 2 credits per call'
operationId: post-goodreads-search
security:
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/is_async'
- $ref: '#/components/parameters/soft_fail'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
query:
type: string
description: 'Required. A book keyword, or a Goodreads search URL (the path contains /search or the query contains q=).
**Example:**
```
dune
```
**URL example:**
```
https://www.goodreads.com/search?q=dune&page=2
```'
page:
type: number
default: '1'
description: 'Optional. Page number, starting at 1. Omitted or blank uses page 1. A value below 1 returns 400. When query is already a Goodreads search URL, this number replaces the page parameter in that URL.
**Example:**
```
2
```'
required:
- query
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
type: object
properties:
id:
type: string
url:
type: string
image:
type: string
title:
type: string
rating:
type: number
series:
type: string
authors:
type: array
items:
type: string
ratings_count:
type: integer
reviews_count:
type: integer
pagination:
type: object
properties:
next:
type: string
page:
type: integer
per_page:
type: integer
total_pages:
type: integer
total_results:
nullable: true
examples:
Dune:
value:
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
'400':
description: Bad Request — missing or invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
'401':
description: Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidKey:
value:
error: Invalid API Key
planRateLimit:
value:
error: 'Rate limit exceeded: You''ve exceeded the per second rate limit on your subscription'
keyQuota:
value:
error: 'Rate limit exceeded for the API key: quota monthly'
'402':
description: Payment Required — your subscription or credit balance is insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Payment required
'500':
description: Internal Server Error — something went wrong on our side.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Error
tags:
- Goodreads
components:
parameters:
fields:
name: fields
in: query
required: false
description: Comma-separated list of response fields to return, with dot notation for nested fields (e.g. `name,location.city`).
schema:
type: string
is_async:
name: is_async
in: query
required: false
description: 'Run the request as a background job: the API answers `202` with a `job_id` to poll on `GET /v1/jobs/{id}`.'
schema:
type: boolean
default: false
soft_fail:
name: soft_fail
in: query
required: false
description: Return HTTP 200 even when the request fails; the error is in the `error` field of the body.
schema:
type: boolean
default: false
schemas:
ErrorResponse:
type: object
required:
- error
properties:
error:
type: string
description: Human-readable error message.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: Your API key. Include it in the x-api-key header for every request.