# 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:** 4 total users, 3 monthly users, 100.0% runs succeeded, 0 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/actors/running/actors-in-store.md#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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# 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(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).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": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,crawlerbros/applepodcasts-listennotes-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/jXRRr6SLyt5WQzyaC/builds/xDax1ZLfDiGmqCJgt/openapi.json