# iTunes Podcast Search & Lookup (`leorochasantos/itunes-podcast-scraper`) Actor Search and lookup podcasts from the iTunes/Apple Podcasts directory via the official Apple API. Returns typed, flat JSON with collection metadata, feed URLs, and optional recent episodes — designed for LLM/MCP consumers. - **URL**: https://apify.com/leorochasantos/itunes-podcast-scraper.md - **Developed by:** [Leonardo Santos](https://apify.com/leorochasantos) (community) - **Categories:** Developer tools, Marketing - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.39 / 1,000 podcast results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 ## iTunes Podcast Search & Lookup Search and lookup podcasts from the iTunes/Apple Podcasts directory via the official Apple API. Returns typed, flat JSON with collection metadata, feed URLs, and optional recent episodes. **No API key required.** The iTunes Search API is public, unauthenticated, and datacenter-open. ### Use cases - **Podcast discovery:** Search by keyword, browse by country - **Podcast enrichment:** Look up metadata by iTunes collection/artist ID - **RSS feed discovery:** Get the `feedUrl` for RSS enrichment in your pipeline - **LLM/MCP integration:** Typed, documented output schema designed for AI consumers - **Competitive research:** Analyze podcast metadata across markets ### Features - **Two modes:** - **Search** by term, with country filter, explicit content filter, and result limit - **Lookup** by collection ID, track ID, or artist ID — with optional recent episodes - **175+ iTunes Store countries** supported (ISO 2-letter codes) - **Flat, typed JSON output** — no nested `body`/`contentType` wrapping - **Feed URL included** when available in Apple's response — enables RSS enrichment - **Error items are free** — invalid IDs or empty results don't count against your usage - **256MB, ~5s per run** — fast and cheap ### Input ```json { "searchTerms": ["technology", "comedy"], "lookupIds": ["863897795"], "country": "US", "maxResults": 25, "includeEpisodes": false, "episodeLimit": 10 } ```` | Field | Type | Default | Description | |-------|------|---------|-------------| | `searchTerms` | string\[] | — | Search terms (leave empty for lookup-only) | | `lookupIds` | string\[] | — | iTunes collection/track/artist IDs (leave empty for search-only) | | `country` | string | `"US"` | ISO 2-letter iTunes Store country | | `maxResults` | integer | `25` | Results per search (1–100) | | `includeEpisodes` | boolean | `false` | Include recent episodes in lookup results | | `episodeLimit` | integer | `10` | Max episodes when includeEpisodes is true | ### Output **One dataset row per podcast** — a search for 25 results gives you 25 rows, ready to filter, sort and export as-is. ```json { "type": "podcast", "searchTerm": "technology", "lookupId": null, "rank": 1, "error": null, "collectionId": 863897795, "trackId": 863897795, "artistName": "Tim Ferriss", "collectionName": "The Tim Ferriss Show", "feedUrl": "https://rss.art19.com/tim-ferriss-show", "primaryGenreName": "Technology", "genres": ["Technology", "Podcasts"], "trackCount": 700, "artworkUrl600": "https://is1-ssl.mzstatic.com/image/...", "releaseDate": "2014-04-23T00:00:00Z", "country": "US", "scraped_at": "2026-07-26T12:00:00.000Z" } ``` A lookup with `includeEpisodes` adds an `episodes` array to the podcast's row; the **Episodes** dataset view expands it to one row per episode. An input that matches nothing still produces exactly one row (`type` `"search"` or `"lookup"`, `resultCount` 0), so every term you send is accounted for in the output. Those rows are never charged. ### Tips - Use `lookupIds` for metadata about known podcasts - Use `searchTerms` for discovery by keyword - Combine both modes in one call to batch research + enrichment - The `feedUrl` field (when present) can be piped into an RSS reader or parser ### Pricing Pay per event, with the platform usage on us — the price you see is the price you pay: - one charge per run, - one charge per **podcast** returned, - one charge per **episode**, only when a lookup asks for them. Rows for inputs that matched nothing (invalid IDs, empty results) are never charged. See the Console for current rates, including the discounts on higher subscription tiers. # Actor input Schema ## `searchTerms` (type: `array`): One or more search terms. Each term produces one dataset item with up to maxResults podcast results. Leave empty for lookup-only mode. ## `lookupIds` (type: `array`): One or more iTunes collection IDs, track IDs, or artist IDs. Each ID produces one dataset item. Leave empty for search-only mode. ## `country` (type: `string`): ISO 2-letter country code for the iTunes Store. Defaults to US. ## `maxResults` (type: `integer`): Maximum results per search term (1–100, defaults to 25). Apple caps at 100. ## `includeEpisodes` (type: `boolean`): If true, lookup results include recent episodes attached to the first podcast result. ## `episodeLimit` (type: `integer`): Maximum episodes to return when includeEpisodes is true (1–100, defaults to 10). ## `proxyConfiguration` (type: `object`): Proxy to use for outgoing requests. The iTunes Search API is datacenter-open — Apify proxy is recommended for volume. ## Actor input object example ```json { "searchTerms": [ "technology", "comedy" ], "lookupIds": [ "863897795" ], "country": "US", "maxResults": 25, "includeEpisodes": false, "episodeLimit": 10, "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `results` (type: `string`): No description # 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 = { "searchTerms": [ "technology", "comedy" ], "lookupIds": [ "863897795" ] }; // Run the Actor and wait for it to finish const run = await client.actor("leorochasantos/itunes-podcast-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 = { "searchTerms": [ "technology", "comedy", ], "lookupIds": ["863897795"], } # Run the Actor and wait for it to finish run = client.actor("leorochasantos/itunes-podcast-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 '{ "searchTerms": [ "technology", "comedy" ], "lookupIds": [ "863897795" ] }' | apify call leorochasantos/itunes-podcast-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=leorochasantos/itunes-podcast-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "iTunes Podcast Search & Lookup", "description": "Search and lookup podcasts from the iTunes/Apple Podcasts directory via the official Apple API. Returns typed, flat JSON with collection metadata, feed URLs, and optional recent episodes — designed for LLM/MCP consumers.", "version": "0.1", "x-build-id": "U82KKamnmQczoouMt" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/leorochasantos~itunes-podcast-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-leorochasantos-itunes-podcast-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/leorochasantos~itunes-podcast-scraper/runs": { "post": { "operationId": "runs-sync-leorochasantos-itunes-podcast-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/leorochasantos~itunes-podcast-scraper/run-sync": { "post": { "operationId": "run-sync-leorochasantos-itunes-podcast-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", "properties": { "searchTerms": { "title": "Search terms", "type": "array", "description": "One or more search terms. Each term produces one dataset item with up to maxResults podcast results. Leave empty for lookup-only mode.", "items": { "type": "string" } }, "lookupIds": { "title": "Lookup IDs", "type": "array", "description": "One or more iTunes collection IDs, track IDs, or artist IDs. Each ID produces one dataset item. Leave empty for search-only mode.", "items": { "type": "string" } }, "country": { "title": "Country", "pattern": "^[A-Z]{2}$", "type": "string", "description": "ISO 2-letter country code for the iTunes Store. Defaults to US.", "default": "US" }, "maxResults": { "title": "Max results per search", "minimum": 1, "maximum": 100, "type": "integer", "description": "Maximum results per search term (1–100, defaults to 25). Apple caps at 100.", "default": 25 }, "includeEpisodes": { "title": "Include episodes", "type": "boolean", "description": "If true, lookup results include recent episodes attached to the first podcast result.", "default": false }, "episodeLimit": { "title": "Episode limit", "minimum": 1, "maximum": 100, "type": "integer", "description": "Maximum episodes to return when includeEpisodes is true (1–100, defaults to 10).", "default": 10 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxy to use for outgoing requests. The iTunes Search API is datacenter-open — Apify proxy is recommended for volume.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } } ```