Datasets API endpoint
Searches the crawled public Apple Podcasts show catalog stored in a search index. One row per show. Discovered from a country x genre x collection chart grid and a search-term sweep — not a full catalog of every Apple Podcasts show. Sort enum: `relevance`, `popularity`, `track_count_desc`, `release_desc`, `title_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/apple-podcasts-shows/searchQuery parameters:
q — full-text query over the show title and artist name (max 256 chars).genre, genre_id, country, explicitness, run_id — exact-match filters (max 128 chars). country is the crawl's discovery storefront (e.g. us, gb), not necessarily every storefront the show is actually available in.min_track_count — minimum episode count (track_count), 0 or greater.sort — one of relevance, popularity, track_count_desc, release_desc, title_asc. Defaults to relevance with q, otherwise popularity (chart seed-rank order).page (default 1), page_size (default 20, max 100). page * page_size must be ≤ 10000.Rows also include feed_url (the show's real podcast RSS feed), artwork_url_600, artist_id/artist_url, genre_ids[]/genres[], discovery_source (chart or search), discovery_country, discovery_genre_id, and discovery_collection. 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 20 checked | Values in the sample |
|---|---|---|
| id | 20 | |
| artist_name | 20 | |
| collection_name | 20 | |
| url | 20 | podcasts.apple.com |
| feed_url | 20 | podcasts.files.bbci.co.uk and 8 other hosts |
| artwork_url_600 | 20 | is1-ssl.mzstatic.com |
| release_date | 20 | 2025-05-22 to 2026-07-22 |
| collection_explicitness | 20 | |
| track_count | 20 | 13 to 274, median 112 |
| country | 20 | |
| currency | 20 | |
| primary_genre_name | 20 | |
| genre_ids | 20 | |
| genres | 20 | median 2 entries |
| content_advisory_rating | 19 | |
| discovery_source | 20 | |
| discovery_country | 20 | |
| discovery_genre_id | 20 | |
| discovery_collection | 20 | |
| seed_rank | 20 | 0 |
| run_id | 20 | |
| crawled_at | 20 | 2026-07-22 |
| schema_version | 20 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| q | string | No | Full-text query over show title and artist name, max 256 characters | ||
| genre | string | No | Exact primary-genre filter (e.g. Comedy, True Crime), max 128 characters | ||
| genre_id | string | No | Exact Apple Podcasts genre id filter (e.g. 1303 for Comedy), max 128 characters | ||
| country | string | No | Exact storefront country filter (the crawl's discovery storefront, e.g. us, gb), max 128 characters | ||
| explicitness | string | No | Exact explicitness filter as reported by Apple (e.g. explicit, cleaned), max 128 characters | ||
| run_id | string | No | Exact crawl run-id filter, max 128 characters | ||
| min_track_count | integer | No | Minimum episode count (track_count), 0 or greater | ||
| sort | string | No | Sort enum: relevance, popularity, track_count_desc, release_desc, title_asc Allowed values: relevance, popularity, track_count_desc, release_desc, title_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/apple-podcasts-shows/search?q=coffee&country=us&sort=relevance&page=1" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "apple-podcasts-shows",
"items": [
{
"id": 173001861,
"artist_name": "Dan Carlin",
"collection_name": "Dan Carlin's Hardcore History",
"feed_url": "https://feeds.example.com/hardcorehistory",
"track_count": 75,
"country": "USA",
"primary_genre_name": "History",
"genre_ids": [
"1301",
"1487"
],
"genres": [
"Arts",
"History"
],
"discovery_source": "chart",
"discovery_country": "us",
"discovery_genre_id": 1487,
"discovery_collection": "toppodcasts",
"seed_rank": 3,
"run_id": "apple-podcasts-20260721",
"crawled_at": "2026-07-21T00:00:00Z",
"schema_version": 1
}
],
"page": 1,
"page_size": 20,
"total": 1,
"sort": "popularity"
}
}Request schema
No body schema
Response schema
#/definitions/datasets.applePodcastsShowsSearchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.ApplePodcastsShowsSearchResponse | No | ||||
| data.dataset | string | No | ||||
| data.items | array | No | ApplePodcastsShowRecord record, 28 fields: artist_id, artist_name, artist_url, artwork_url_600, collection_explicitness, collection_name, content_advisory_rating, country, crawled_at, currency, discovery_collection, discovery_country and 16 more. Described under Apple Podcasts Show Dataset Item API. | |||
| data.page | integer | No | ||||
| data.page_size | integer | No | ||||
| data.sort | string | No | ||||
| data.total | integer | 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-podcasts-shows/search?q=coffee&country=us&sort=relevance&page=1" \
-H "x-api-key: $CRAWLORA_API_KEY"