Apify Public Data & Leads

Apple Podcasts Search & Episode Feeds

apple_podcasts_data

Read-only

Search Apple Podcasts by keyword or fetch exact shows and recent episodes using Apple IDs, podcast URLs, or RSS feeds, returning show and episode metadata for datasets and AI pipelines.

Instructions

Get Apple Podcasts data from Apple's public directory plus each show's own public RSS feed in one call: keyword search across store countries, exact shows by Apple id / podcasts.apple.com URL / any RSS feed URL, and the newest episodes of each show with publication date, duration, audio file URL and episode page URL. Podcast rows carry Apple id, name, publisher, genre, artwork, Apple page URL, feed URL and reported episode count; episode rows carry title, episode and season number, publishedAt (ISO 8601), durationSeconds, audioUrl, episodeUrl and feed guid.

Behavioral Transparency:

Execution: Network call executed synchronously in the cloud via Apify Actor 'captainhandsome/apple-podcasts-scraper'.
Side Effects: Reads Apple's public iTunes search/lookup endpoints and public podcast RSS feeds; creates a billed Actor run and dataset on your Apify account. No login, no API key, no browser.
Authentication: Requires APIFY_TOKEN environment variable.
Latency & Limits: Typically a few seconds to a minute depending on how many feeds are read (20s timeout per feed, up to 100 targets per run). Starts from $0.0015 per row plus a small per-run start fee. One call returns at most 100 rows, and every row the Actor produces is billed (one row per show plus one per episode), so keep shows x (1 + max_episodes_per_podcast) at or below 100.

Usage Guidelines:

When to use: Use to build podcast or episode datasets, monitor new episodes of specific shows, research shows by keyword or genre, or feed episode metadata into transcription and AI pipelines.
When NOT to use: Do not use for transcripts or audio files themselves (this returns metadata and audio URLs only), for Apple Podcasts ratings or reviews (Apple publishes no reliably fetchable form of them), or for Spotify-only or private/paywalled shows.
Named alternatives: Use 'apple_app_store_data' for App Store apps; use a dedicated transcription Actor when you need spoken-word text.

Honest limits: episodes come from each show's public RSS feed, so fields a publisher does not state (duration, episode number, season) are returned as null rather than invented; shows that publish no public feed are logged and skipped; a run that can read nothing fails loudly instead of charging for an empty dataset. Directory search is capped at 200 shows per keyword by Apple.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "apple_podcasts_data"
  }
}

Input Schema

Name	Required	Description
`countries`	No	Two-letter Apple Podcasts store codes (us, gb, de, jp, ...). Each country is searched separately and tagged on the row; defaults to us.
`podcast_refs`	No	Exact shows to read: numeric Apple podcast ids ('1236907421'), podcasts.apple.com URLs, or any public RSS feed URL.
`search_terms`	No	Podcast keywords to search in the Apple Podcasts directory. Each keyword returns up to max_podcasts_per_term shows per country. Leave out (or pass []) when you only pass podcast_refs; nothing is searched then.
`max_podcasts_per_term`	No	How many shows to take per keyword. Each show is a billed row and adds its episodes; defaults to 3.
`max_episodes_per_podcast`	No	How many of the newest episodes to return per show. Set 0 for podcast metadata only. Each row is billed; defaults to 20.

Output Schema

Name	Required	Description	Default
`run`	No
`error`	No
`status`	Yes
`results`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.6.0Nov 12, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnly/openWorld/non-idempotent/non-destructive; the description adds what annotations cannot — synchronous cloud execution via a named Apify Actor, APIFY_TOKEN requirement, per-row and per-run billing, a 20s per-feed timeout, 100-target and 100-row caps, and null-instead-of-invented fields. It also discloses failure behavior (unreadable feeds logged and skipped; an entirely empty run fails loudly rather than billing) and Apple's 200-shows-per-keyword search cap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the capability sentence, then cleanly sectioned under Behavioral Transparency / Usage Guidelines / Honest limits, so an agent can skim to the needed part. Minor redundancy: the Podcast and episode row field enumerations largely duplicate the existing output schema, costing a sentence or two of length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers everything material for a 5-parameter, zero-required, billable scraping tool with an output schema: auth, cost model, hard caps, timeout, null semantics, skip and failure behavior. Because an output schema exists, the row-field listing is a bonus rather than a required burden.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by stating the row-budget interaction between parameters ('keep shows x (1 + max_episodes_per_podcast) at or below 100') and clarifying that refs-only calls perform no search. It does not restate per-parameter formats like the two-letter country codes, which the schema already covers.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource ('Get Apple Podcasts data') plus the three access modes — keyword search by store country, exact lookup by Apple id / podcasts.apple.com URL / RSS URL, and newest episodes per show. It explicitly distinguishes itself from 'apple_app_store_data', so an agent can separate it from the nearest sibling without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Has an explicit 'When to use' list, a 'When NOT to use' list (transcripts/audio, ratings/reviews, Spotify-only or private shows), and named alternatives including 'apple_app_store_data' and a dedicated transcription Actor. The boundary conditions an agent would otherwise guess at are spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server