Datasets API endpoint
Returns term counts over the same filters as search. Facet values: `kind`, `genres`, `artist_name`, `publisher`, `series_name`, `narrator`, `provider`, `currency`, `discovery_country`, `discovery_source`, `free`.
/datasets/apple-books/facetsMCP tool: datasets_apple_books_facets
Returns term counts for a required facet, honoring the same search filters as
the Apple Books dataset search endpoint. Allowed facets: kind, genres,
artist_name, publisher, series_name, narrator, provider, currency,
discovery_country, discovery_source, free.
Search filters such as q, kind, genre, artist, publisher, series,
narrator, provider, currency, country, discovery_source, free,
min_rating and min_rating_count can be supplied to scope the aggregation.
Filter kind values are book, audiobook, author, series,
audiobook_series. The search sort values are relevance (with q),
rating_count_desc, rating_desc, release_date_desc, name_asc, and
crawled_at_desc.
The response includes the dataset id, chosen facet, and items with value
and count.
| Field | Filled in, of 5 checked |
|---|---|
| count | 5 |
| value | 5 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| facet | string | Yes | Facet: kind, genres, artist_name, publisher, series_name, narrator, provider, currency, discovery_country, discovery_source, free Allowed values: kind, genres, artist_name, publisher, series_name, narrator, provider, currency, discovery_country, discovery_source, free. | kind | |
| q | string | No | Full-text query over name, artist, series, narrator and description; max 256 characters | ||
| kind | string | No | Record kind: book, audiobook, author, series, audiobook_series Allowed values: book, audiobook, author, series, audiobook_series. | ||
| genre | string | No | Exact Apple Books genre label, max 128 characters | ||
| artist | string | No | Exact author or artist name, max 128 characters | ||
| artist_id | string | No | Exact numeric Apple Books artist ID, max 128 characters | ||
| publisher | string | No | Exact ebook publisher, max 128 characters | ||
| series | string | No | Exact series name, max 128 characters | ||
| narrator | string | No | Exact audiobook narrator, max 128 characters | ||
| provider | string | No | Exact audiobook provider, max 128 characters | ||
| currency | string | No | Exact currency code, max 128 characters | ||
| country | string | No | Exact discovery storefront country, max 128 characters | ||
| discovery_source | string | No | Exact crawl source, max 128 characters | ||
| free | boolean | No | Filter for free titles | ||
| min_rating | number | No | Minimum average rating from 0 through 5 | ||
| min_rating_count | integer | No | Minimum rating count, 0 or greater | ||
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/datasets/apple-books/facets?facet=kind&q=coffee&kind=book&country=us&free=true" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "apple-books",
"facet": "kind",
"items": [
{
"value": "audiobook",
"count": 609767
}
]
}
}Request schema
No body schema
Response schema
#/definitions/datasets.appleBooksFacetResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.AppleBooksFacetResponse | 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/apple-books/facets?facet=kind&q=coffee&kind=book&country=us&free=true" \
-H "x-api-key: $CRAWLORA_API_KEY"