# Apple Podcasts + Listen Notes Scraper (`crawlerbros/applepodcasts-listennotes-scraper`) Actor Scrape podcast and episode data from Apple Podcasts (free, no auth) or Listen Notes (free tier with API key). Search, lookup-by-ID, top charts, best podcasts by genre, episodes, and trending. - **URL**: https://apify.com/crawlerbros/applepodcasts-listennotes-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Developer tools, Automation, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 8 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Apple Podcasts + Listen Notes Scraper Scrape **Apple Podcasts** and **Listen Notes** — the two most comprehensive global podcast directories — through one combined actor with a single `platform` switch. - **Apple Podcasts** uses the public iTunes Search API. **No login, no API key, no proxy required.** - **Listen Notes** uses its official REST API. **Free tier (250 calls/month) requires only an API key.** ### What you get #### Apple Podcasts surface - **Search podcasts** by free-text query, country store, and genre. - **Lookup by podcast ID** (numeric Apple `collectionId`) — batch up to 100 IDs per call. - **Top podcasts charts** — RSS feeds covering 47 countries and 19 genres, refreshed live by Apple. Fields: `podcastId`, `title`, `publisher`, `publisherId`, `url`, `feedUrl`, `publisherUrl`, `primaryGenre`, `genres[]`, `artworkUrl` (600x600), `country`, `currency`, `episodeCount`, `releaseDate`, `explicitness`, `advisoryRating`, `summary`, `copyright`. #### Listen Notes surface - **Search podcasts / episodes / curated lists** by query, with language / region / genre filters. - **Best podcasts by genre** — Listen Notes' editorial top picks for any genre. - **Genres index** — list every Listen Notes genre with parent / child relationships. - **Trending typeahead** — discover currently popular shows. - **Podcast / episode detail by ID** — full metadata. Fields: `podcastId`, `title`, `publisher`, `description`, `url`, `feedUrl`, `websiteUrl`, `artworkUrl`, `language`, `country`, `genreIds[]`, `episodeCount`, `listenScore`, `listenScoreGlobalRank`, `latestPubDate`, `earliestPubDate`, `updateFrequencyHours`, `social{twitter, facebook, instagram, youtube, ...}`, `itunesId`, `explicitContent`, `isClaimed`. Episodes additionally carry `audioUrl`, `audioLengthSec`, embedded `podcast{}` reference. ### Modes | Mode | Apple | Listen Notes | Description | |---|:---:|:---:|---| | `searchPodcasts` | ✓ | ✓ | Free-text search for podcasts | | `lookupById` | ✓ | — | Apple lookup by collectionId (batched 100/call) | | `topPodcasts` | ✓ | — | Apple top RSS chart by country + genre | | `searchEpisodes` | — | ✓ | Listen Notes episode search | | `searchCurated` | — | ✓ | Listen Notes curated-list search | | `podcastById` | — | ✓ | Listen Notes podcast detail | | `episodeById` | — | ✓ | Listen Notes episode detail | | `bestPodcasts` | — | ✓ | Listen Notes editorial picks per genre / region | | `genres` | — | ✓ | List all Listen Notes genres with parent / child | | `trending` | — | ✓ | Listen Notes typeahead (trending shows) | ### Filters - **Country** — 47 ISO 3166-1 alpha-2 codes (US, GB, DE, JP, BR, etc.) for Apple stores. - **Apple genre** — 19 top-level genres (Arts, Business, Comedy, Education, News, Technology, True Crime, …). - **Listen Notes region / language** — restrict results by ISO country and language name. - **Listen Notes safe mode** — filter out explicit content (default on). - **Listen Notes sort by date** — newest-first ordering on search. - **Min last episode days** — drop podcasts whose latest episode is older than N days. - **Max items** — hard cap on records emitted (1–1000). ### Example input — daily test ```json { "platform": "applePodcasts", "mode": "topPodcasts", "country": "us", "appleGenre": "technology", "maxItems": 10 } ```` Returns the top 10 technology podcasts in the US store, ranked by Apple's live chart. **No API key required.** ### Example output (truncated) ```json { "platform": "applePodcasts", "recordType": "podcast", "podcastId": "1200361736", "title": "The Daily", "publisher": "The New York Times", "url": "https://podcasts.apple.com/us/podcast/the-daily/id1200361736?uo=4", "primaryGenre": "Daily News", "artworkUrl": "https://is1-ssl.mzstatic.com/image/.../600x600bb.jpg", "summary": "This is what the news should sound like…", "scrapedAt": "2025-01-01T00:00:00+00:00" } ``` ### FAQ **Do I need an API key?** Only for Listen Notes. Apple Podcasts is fully public — switch `platform` to `applePodcasts` and you're set. **How do I get a Listen Notes key?** Sign up at [listennotes.com/api](https://www.listennotes.com/api/). The free tier gives you 250 calls/month; paid tiers start at $180/month for higher quotas. **Do you support Spotify / Stitcher / Audible?** Not yet. Apple + Listen Notes already cover ~90% of public RSS-distributed podcasts. Spotify-exclusive shows are not in either index. **How fresh is Apple's top-podcasts chart?** Apple updates these RSS feeds approximately every 1–2 hours. **Can I get all episodes of a podcast?** From Apple, you'll need the `feedUrl` and parse the RSS yourself. From Listen Notes, the `/podcasts/{id}` endpoint includes recent episodes. **Why are some fields missing from records?** The actor follows an "omit-empty" policy — fields the upstream API doesn't populate are excluded entirely (rather than emitting `null`). ### Limitations - iTunes Search caps at ~20 requests/min/IP. The actor sleeps ~0.6s between calls and retries with `Retry-After` honor on 429s. - Listen Notes free tier is 250 calls/month; one search call equals one quota unit. - Apple's RSS top charts return at most 200 entries per country/genre; for deeper coverage, use `searchPodcasts`. - Spotify-exclusive podcasts are not represented in either directory. # Actor input Schema ## `platform` (type: `string`): Which podcast directory to scrape. ## `mode` (type: `string`): What to fetch. Apple supports: searchPodcasts, searchEpisodes, lookupById, topPodcasts. Listen Notes supports: searchPodcasts, searchEpisodes, searchCurated, podcastById, episodeById, bestPodcasts, genres, trending. ## `searchQuery` (type: `string`): Free-text query for any `search*` mode. Example: `marketing podcast`. ## `country` (type: `string`): ISO 3166-1 alpha-2 country code for the Apple store / RSS region. Affects `searchPodcasts`, `lookupById`, `topPodcasts`. ## `appleGenre` (type: `string`): Apple Podcasts genre slug. Used by `mode=topPodcasts` to filter the chart by category. ## `appleIds` (type: `array`): Numeric Apple Podcast collection IDs (e.g. `1200361736` for The Daily). Each ID is fetched via the iTunes Lookup API. ## `listenNotesApiKey` (type: `string`): Free or paid Listen Notes API key (https://www.listennotes.com/api/). Required only when `platform=listenNotes`. Example: 32-char hex. ## `listenNotesIds` (type: `array`): Listen Notes IDs (32-char hash strings). ## `listenNotesGenreId` (type: `integer`): Listen Notes numeric genre ID. Use `mode=genres` first to discover IDs (e.g. 67=Technology, 99=News, 93=Business). ## `listenNotesType` (type: `string`): Result type for Listen Notes search. ## `listenNotesRegion` (type: `string`): ISO 3166-1 alpha-2 country code restricting Listen Notes results. ## `listenNotesLanguage` (type: `string`): Filter Listen Notes results to a specific language. ## `listenNotesSafeMode` (type: `boolean`): If on, Listen Notes excludes explicit content (`safe_mode=1`). ## `listenNotesSortByDate` (type: `boolean`): If on, Listen Notes search results are sorted by date (newest first) instead of relevance. ## `minLastEpisodeDays` (type: `integer`): Drop podcasts whose latest episode is older than N days. Use `30` to keep only podcasts that released an episode in the last month. `0` = disabled. ## `maxItems` (type: `integer`): Hard cap on emitted records. Example: `100`. ## Actor input object example ```json { "platform": "applePodcasts", "mode": "topPodcasts", "country": "us", "appleGenre": "technology", "appleIds": [], "listenNotesIds": [], "listenNotesType": "podcast", "listenNotesSafeMode": true, "listenNotesSortByDate": false, "maxItems": 10 } ``` # Actor output Schema ## `records` (type: `string`): Dataset containing all scraped podcast / episode records. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "platform": "applePodcasts", "mode": "topPodcasts", "country": "us", "appleGenre": "technology", "listenNotesSafeMode": true, "listenNotesSortByDate": false, "maxItems": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/applepodcasts-listennotes-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "platform": "applePodcasts", "mode": "topPodcasts", "country": "us", "appleGenre": "technology", "listenNotesSafeMode": True, "listenNotesSortByDate": False, "maxItems": 10, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/applepodcasts-listennotes-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "platform": "applePodcasts", "mode": "topPodcasts", "country": "us", "appleGenre": "technology", "listenNotesSafeMode": true, "listenNotesSortByDate": false, "maxItems": 10 }' | apify call crawlerbros/applepodcasts-listennotes-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/applepodcasts-listennotes-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Apple Podcasts + Listen Notes Scraper", "description": "Scrape podcast and episode data from Apple Podcasts (free, no auth) or Listen Notes (free tier with API key). Search, lookup-by-ID, top charts, best podcasts by genre, episodes, and trending.", "version": "1.0", "x-build-id": "xDax1ZLfDiGmqCJgt" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~applepodcasts-listennotes-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-applepodcasts-listennotes-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~applepodcasts-listennotes-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-applepodcasts-listennotes-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~applepodcasts-listennotes-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-applepodcasts-listennotes-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "platform", "mode" ], "properties": { "platform": { "title": "Platform", "enum": [ "applePodcasts", "listenNotes" ], "type": "string", "description": "Which podcast directory to scrape.", "default": "applePodcasts" }, "mode": { "title": "Mode", "enum": [ "searchPodcasts", "lookupById", "topPodcasts", "searchEpisodes", "searchCurated", "podcastById", "episodeById", "bestPodcasts", "genres", "trending" ], "type": "string", "description": "What to fetch. Apple supports: searchPodcasts, searchEpisodes, lookupById, topPodcasts. Listen Notes supports: searchPodcasts, searchEpisodes, searchCurated, podcastById, episodeById, bestPodcasts, genres, trending.", "default": "topPodcasts" }, "searchQuery": { "title": "Search query", "type": "string", "description": "Free-text query for any `search*` mode. Example: `marketing podcast`." }, "country": { "title": "Apple country / store", "enum": [ "us", "gb", "ca", "au", "de", "fr", "es", "it", "nl", "se", "dk", "no", "fi", "ie", "be", "at", "ch", "pt", "pl", "br", "mx", "ar", "cl", "co", "jp", "kr", "cn", "tw", "hk", "sg", "in", "id", "ph", "th", "my", "vn", "tr", "ru", "ua", "il", "sa", "ae", "eg", "za", "ng", "ke", "nz" ], "type": "string", "description": "ISO 3166-1 alpha-2 country code for the Apple store / RSS region. Affects `searchPodcasts`, `lookupById`, `topPodcasts`.", "default": "us" }, "appleGenre": { "title": "Apple Podcasts genre (mode=topPodcasts)", "enum": [ "", "arts", "business", "comedy", "education", "fiction", "government", "health", "history", "kids-family", "leisure", "music", "news", "religion-spirituality", "science", "society-culture", "sports", "technology", "true-crime", "tv-film" ], "type": "string", "description": "Apple Podcasts genre slug. Used by `mode=topPodcasts` to filter the chart by category.", "default": "technology" }, "appleIds": { "title": "Apple Podcast IDs (mode=lookupById)", "type": "array", "description": "Numeric Apple Podcast collection IDs (e.g. `1200361736` for The Daily). Each ID is fetched via the iTunes Lookup API.", "default": [], "items": { "type": "string" } }, "listenNotesApiKey": { "title": "Listen Notes API key", "type": "string", "description": "Free or paid Listen Notes API key (https://www.listennotes.com/api/). Required only when `platform=listenNotes`. Example: 32-char hex." }, "listenNotesIds": { "title": "Listen Notes podcast / episode IDs (mode=podcastById / episodeById)", "type": "array", "description": "Listen Notes IDs (32-char hash strings).", "default": [], "items": { "type": "string" } }, "listenNotesGenreId": { "title": "Listen Notes genre ID (mode=bestPodcasts)", "minimum": 1, "maximum": 9999, "type": "integer", "description": "Listen Notes numeric genre ID. Use `mode=genres` first to discover IDs (e.g. 67=Technology, 99=News, 93=Business)." }, "listenNotesType": { "title": "Listen Notes search type", "enum": [ "podcast", "episode", "curated" ], "type": "string", "description": "Result type for Listen Notes search.", "default": "podcast" }, "listenNotesRegion": { "title": "Listen Notes region (mode=bestPodcasts)", "enum": [ "", "us", "gb", "ca", "au", "de", "fr", "es", "it", "nl", "se", "br", "mx", "jp", "kr", "in", "sg", "nz", "za" ], "type": "string", "description": "ISO 3166-1 alpha-2 country code restricting Listen Notes results." }, "listenNotesLanguage": { "title": "Listen Notes language", "enum": [ "", "English", "Spanish", "Portuguese", "French", "German", "Italian", "Russian", "Japanese", "Korean", "Chinese", "Arabic", "Dutch", "Swedish", "Polish", "Turkish", "Hindi" ], "type": "string", "description": "Filter Listen Notes results to a specific language." }, "listenNotesSafeMode": { "title": "Safe mode (Listen Notes)", "type": "boolean", "description": "If on, Listen Notes excludes explicit content (`safe_mode=1`).", "default": true }, "listenNotesSortByDate": { "title": "Sort by date (Listen Notes search)", "type": "boolean", "description": "If on, Listen Notes search results are sorted by date (newest first) instead of relevance.", "default": false }, "minLastEpisodeDays": { "title": "Active podcasts only (last N days)", "minimum": 0, "maximum": 36500, "type": "integer", "description": "Drop podcasts whose latest episode is older than N days. Use `30` to keep only podcasts that released an episode in the last month. `0` = disabled." }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Hard cap on emitted records. Example: `100`.", "default": 50 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```