Goodreads API endpoint
Returns up to 50 books on a Goodreads genre/shelf tag page (e.g. fantasy, romance, science-fiction), Goodreads' per-tag "top books" view: title, author, average rating, ratings count, publication year, and how many times the book was shelved under this specific tag. Goodreads' genre/shelf taxonomy is an open, user-generated folksonomy of thousands of tags, not a small fixed list, so there is no directory endpoint — pass any known tag slug, e.g. from a book's genres[] field or a value seen on goodreads.com. There is no pagination beyond the first 50.
/goodreads/genre/{name}Path parameters:
name (required) — Goodreads genre/shelf tag, e.g. fantasy.Response includes name, source_url, and books[] (id, title, author, author_id, average_rating, ratings_count, publication_year, shelved_count, uri).
| Field | Filled in, of 50 checked | Values in the sample |
|---|---|---|
| id | 50 | |
| title | 50 | |
| author | 50 | |
| author_id | 50 | |
| average_rating | 50 | 3.68 to 4.66, median 4.36 |
| ratings_count | 50 | 448,540 to 11,867,041, median 1,793,915 |
| publication_year | 50 | 1,937 to 2,023, median 2,007 |
| shelved_count | 50 | 24,774 to 90,783, median 33,146 |
| uri | 50 | goodreads.com |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| name (path) | string | Yes | Goodreads genre/shelf tag | fantasy | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/goodreads/genre/fantasy" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"name": "fantasy",
"books": [
{
"id": "42844155",
"title": "Harry Potter and the Philosopher's Stone (Harry Potter, #1)",
"author": "J.K. Rowling",
"author_id": "1077326",
"average_rating": 4.47,
"ratings_count": 11710306,
"publication_year": 1997,
"shelved_count": 89892,
"uri": "https://www.goodreads.com/book/show/42844155-harry-potter-and-the-philosopher-s-stone"
},
{
"id": "5907",
"title": "The Hobbit, or There and Back Again (Paperback)",
"author": "J.R.R. Tolkien",
"author_id": "656983",
"average_rating": 4.3,
"ratings_count": 4585794,
"publication_year": 1937,
"shelved_count": 73195,
"uri": "https://www.goodreads.com/book/show/5907.The_Hobbit"
}
]
},
"source_url": "https://www.goodreads.com/shelf/show/fantasy"
}Request schema
No body schema
Response schema
#/definitions/goodreads.genreResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | goodreads.GenreResponse | No | ||||
| data.books | array | No | ||||
| data.books[].author | string | No | ||||
| data.books[].author_id | string | No | ||||
| data.books[].average_rating | number | No | 4.47 | |||
| data.books[].id | string | No | ||||
| data.books[].publication_year | integer | No | ||||
| data.books[].ratings_count | integer | No | ||||
| data.books[].shelved_count | integer | No | ShelvedCount is how many users have shelved this specific book under this genre tag — a per-genre popularity signal distinct from the book's overall ratings_count. | |||
| data.books[].title | string | No | ||||
| data.books[].uri | string | No | ||||
| data.name | string | No | ||||
| data.source_url | string | No | ||||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 404 | Not Found | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/goodreads/genre/fantasy" \
-H "x-api-key: $CRAWLORA_API_KEY"