Apple Podcasts Search, Charts and Episodes

Search Apple Podcasts, export country charts, look up podcast metadata, and collect recent episodes with descriptions and audio links. It does not download audio, collect reviews or ratings, or recover a complete episode archive.

Input

The default collects 10 science podcasts from the US storefront:

{"mode":"search","searchTerm":"science","country":"us","maxResults":10}

Use mode: "charts" for country rankings (up to 100), details for podcast metadata, or episodes for recent episodes. Details and episodes require podcasts, an array of Apple IDs or Apple Podcasts URLs. maxEpisodesPerPodcast defaults to 10 and cannot exceed 200. Availability varies by storefront.

{"mode":"episodes","podcasts":["979020229"],"country":"us","maxEpisodesPerPodcast":10}

Search has a 200-result ceiling and no pagination. Optional genreId filters the returned search results; it can yield fewer rows because matching podcasts outside the capped response are unavailable. Genre charts are not supported. Set includeOwnerContact: true in details mode to add the publisher's explicitly supplied RSS owner name and email; the default excludes them.

Output

Rows have rowType, podcastId, and a canonical url:

• podcast: title, author, genres, artwork URL, feed URL, episode count and last release.
• chart: title, author, artwork, genres, country and rank.
• episode: title, date, duration in seconds, plain description, audio URL and episode URL.
• owner: ownerName and ownerEmail, only when requested in details mode.

Output example

{"rowType":"episode","podcastId":979020229,"episodeId":1000798431669,"url":"https://podcasts.apple.com/us/podcast/id979020229?i=1000798431669","title":"Personal AI Agents for Pythonistas","date":"2026-10-27T22:27:47+00:00","durationSeconds":3998,"description":"Episode description","audioUrl":"https://talkpython.fm/episodes/download/567/personal-ai-agents-for-pythonistas.mp3?v=2","episodeUrl":"https://podcasts.apple.com/us/podcast/personal-ai-agents-for-pythonistas/id979020229?i=1000798431669&uo=4"}

Missing source fields are null. Episode count can exceed the number Apple makes available. Results save per target; partial runs retain saved rows and name failed targets in the run status. An unavailable source with no saved rows fails; confirmed empty results succeed. Large target lists may stop at the run deadline. Requests are paced, so increase run timeout for larger collections.

Local use

Install requirements-dev.txt in a virtual environment, run python -m unittest discover -s tests, and start with python -m src.

Start charges, where configured, apply per GB of memory, rounded up; the default 512 MB run is one start unit.