Datasets API endpoint
Searches the crawled public Goodreads author profile index. Authors are discovered as a byproduct of the books crawl (every credited book contributor, plus the genre/search/list seed sources) — not a full catalog. Sort enum: `relevance`, `rating_desc`, `reviews_desc`, `name_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).
/datasets/goodreads-authors/searchQuery parameters:
q — full-text query over name, about and genres (max 256 chars).name, genre, run_id — exact-match filters (max 128 chars).min_rating (0–5), min_ratings_count — numeric filters.sort — one of relevance, rating_desc, reviews_desc, name_asc. Defaults to relevance with q, otherwise reviews_desc (popularity by ratings count).page (default 1), page_size (default 20, max 100). page * page_size must be ≤ 10000.Returns {dataset, items[], page, page_size, total, sort}. An empty or not-yet-populated dataset returns an empty items list, not an error.
1 credit per record returned, minimum 2. A search that returns 20 records costs 20 credits, a full page of 100 costs 100, and an empty or one-record result costs 2. You are charged for what comes back, not for the page_size you ask for, but your balance must cover the requested page_size for the call to be accepted. The response header x-credit-cost shows what a call was charged.
| Field | Filled in, of 1 checked | Values in the sample |
|---|---|---|
| id | 1 | |
| name | 1 | |
| website | 1 | anahuang.com |
| genres | 1 | median 3 entries |
| about | 1 | median 470 characters |
| image_url | 1 | images.gr-assets.com |
| average_rating | 1 | 3.92 |
| ratings_count | 1 | 6,797,462 |
| reviews_count | 1 | 582,270 |
| uri | 1 | goodreads.com |
| source_url | 1 | goodreads.com |
| seed_rank | 1 | 863 |
| discovery_source | 1 | |
| run_id | 1 | |
| crawled_at | 1 | 2026-07-20 |
| schema_version | 1 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| q | string | No | Full-text query over name, about and genres, max 256 characters | ||
| name | string | No | Exact author name filter, max 128 characters | ||
| genre | string | No | Exact genre filter (e.g. Fantasy, Romance, Nonfiction), max 128 characters | ||
| run_id | string | No | Exact crawl run-id filter, max 128 characters | ||
| min_rating | number | No | Minimum average rating, 0 through 5 | ||
| min_ratings_count | integer | No | Minimum number of ratings | ||
| sort | string | No | Sort enum: relevance, rating_desc, reviews_desc, name_asc Allowed values: relevance, rating_desc, reviews_desc, name_asc. | ||
| page | integer | No | 1 | Page number, defaults to 1 | |
| page_size | integer | No | 20 and maxes at 100 | Page size, defaults to 20 and maxes at 100; page * page_size must be <= 10000 | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/datasets/goodreads-authors/search?q=coffee&sort=relevance&page=1" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "goodreads-authors",
"items": [
{
"id": "153394",
"name": "Suzanne Collins",
"birth_date": "August 11, 1962",
"website": "http://suzannecollinsbooks.com",
"genres": [
"Young Adult",
"Fantasy"
],
"about": "Suzanne Collins is the author of...",
"average_rating": 4.3,
"ratings_count": 20189669,
"reviews_count": 900123
}
],
"page": 1,
"page_size": 20,
"total": 1,
"sort": "reviews_desc"
}
}Request schema
No body schema
Response schema
#/definitions/datasets.goodreadsAuthorsSearchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.GoodreadsAuthorSearchResponse | No | ||||
| data.dataset | string | No | Identifier of the dataset queried (`goodreads-authors`). | |||
| data.items | array | No | Matching Goodreads author records on this page. | |||
| data.items[].about | string | No | Author biography from the Goodreads page. | |||
| data.items[].average_rating | number | No | Average rating across the author's books on Goodreads. | |||
| data.items[].birth_date | string | No | Birth date as Goodreads shows it, for example `August 11, 1962`. | |||
| data.items[].crawled_at | string | No | Time the author's data was fetched, in UTC (RFC 3339). | |||
| data.items[].death_date | string | No | Date of death as Goodreads shows it. | |||
| data.items[].discovery_source | string | No | DiscoverySource records how this id was found, e.g. "book:2767052", "genre:fantasy", "search:mystery" — useful for crawl provenance/debugging. | |||
| data.items[].genres | array | No | List of genres Goodreads shows for the author. | |||
| data.items[].id | string | No | Goodreads author id. | |||
| data.items[].image_url | string | No | URL of the author's photo. | |||
| data.items[].name | string | No | Full name of the author. | |||
| data.items[].ratings_count | integer | No | Number of ratings the author's books have received. | |||
| data.items[].reviews_count | integer | No | Number of reviews the author's books have received. | |||
| data.items[].run_id | string | No | Identifier of the collection run that produced this record. Accepted as a `run_id` filter. | |||
| data.items[].schema_version | integer | No | Version of the record layout. | |||
| data.items[].seed_rank | integer | No | SeedRank is the discovery priority (lower = discovered earlier/higher priority), mirroring GoodreadsBookRecord.SeedRank. | |||
| data.items[].source_url | string | No | URL the data was read from. | |||
| data.items[].uri | string | No | Link to the author's Goodreads page. | |||
| data.items[].website | string | No | Author's website address. | |||
| data.page | integer | No | Page number returned. | |||
| data.page_size | integer | No | Number of items per page. | |||
| data.sort | string | No | Sort order applied. | |||
| data.total | integer | No | Total number of records matching the filters. | |||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/datasets/goodreads-authors/search?q=coffee&sort=relevance&page=1" \
-H "x-api-key: $CRAWLORA_API_KEY"