Datasets API endpoint
Returns terms aggregation counts for the Goodreads books dataset. Facet enum: `genres`, `format`, `language`, `publisher`, `primary_author`, `primary_author_id`, `series_name`, `publication_year`, `run_id`.
/datasets/goodreads-books/facetsReturns terms-aggregation counts for one field over the Goodreads books dataset, honoring the same filters as search.
Query parameters:
facet (required) — one of genres, format, language, publisher, primary_author, primary_author_id, series_name, publication_year, run_id.q, genre, format, language, publisher, author, author_id, series, isbn, isbn13, run_id, min_rating, min_ratings_count, min_pages, max_pages, min_publication_year, max_publication_year) apply.Returns {dataset, facet, items:[{value, count}]} (top 50 buckets).
| Field | Filled in, of 50 checked | Values in the sample |
|---|---|---|
| value | 50 | |
| count | 50 | 65,834 to 1,015,017, median 133,555 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| facet | string | Yes | Facet enum: genres, format, language, publisher, primary_author, primary_author_id, series_name, publication_year, run_id Allowed values: genres, format, language, publisher, primary_author, primary_author_id, series_name, publication_year, run_id. | genres | |
| q | string | No | Full-text query over title, author and description, max 256 characters | ||
| genre | string | No | Exact genre filter, max 128 characters | ||
| format | string | No | Exact format filter, max 128 characters | ||
| language | string | No | Exact language filter, max 128 characters | ||
| publisher | string | No | Exact publisher filter, max 128 characters | ||
| author | string | No | Exact author name filter, max 128 characters | ||
| author_id | string | No | Exact Goodreads author id filter, max 128 characters | ||
| series | string | No | Exact series name filter, max 128 characters | ||
| isbn | string | No | Exact ISBN-10 filter, max 128 characters | ||
| isbn13 | string | No | Exact ISBN-13 filter, 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 | ||
| min_pages | integer | No | Minimum page count | ||
| max_pages | integer | No | Maximum page count | ||
| min_publication_year | integer | No | Minimum publication year | ||
| max_publication_year | integer | No | Maximum publication year | ||
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/datasets/goodreads-books/facets?facet=genres&q=coffee&language=en" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "goodreads-books",
"facet": "genres",
"items": [
{
"value": "Fiction",
"count": 412
},
{
"value": "Fantasy",
"count": 238
}
]
}
}Request schema
No body schema
Response schema
#/definitions/datasets.goodreadsBooksFacetResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.GoodreadsFacetResponse | No | ||||
| data.dataset | string | No | ||||
| data.facet | string | No | ||||
| data.items | array | No | ||||
| data.items[].count | integer | No | ||||
| data.items[].value | string | No | ||||
| 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-books/facets?facet=genres&q=coffee&language=en" \
-H "x-api-key: $CRAWLORA_API_KEY"