# Listen Notes

> Search Listen Notes' podcast database: find episodes and shows by topic or name, pull a podcast's or episode's full details including its audio URL, and browse the best podcasts by genre.

App · Music & Podcasts · 4 actions. Web page: https://docs.lodol.com/docs/integrations/listen-notes

## Actions

### Get a podcast

Get one podcast's metadata by its Listen Notes id, including publisher, description, episode count, RSS feed, and its Listen Score popularity rating.

**Inputs**

- Podcast ID (`podcast_id`, text, required): The Listen Notes id of the podcast. Search podcasts first if you only have the name.

**Outputs**

- `podcast` (object): The podcast's metadata.

**Example output**

```json
{
  "podcast": {
    "country": "United States",
    "description": "The a16z Podcast discusses tech and culture trends, news, and the future, especially as 'software eats the world'.",
    "earliest_pub_date_ms": 1427212800000,
    "explicit_content": false,
    "genre_ids": [
      127,
      67,
      93
    ],
    "id": "4d3fe717742d4963a85562e9f84d8c79",
    "image": "https://production.listennotes.com/podcasts/a16z-podcast-image.jpg",
    "itunes_id": 842818711,
    "language": "English",
    "latest_pub_date_ms": 1706644800000,
    "listen_score": 78,
    "listen_score_global_rank": "0.01%",
    "listennotes_url": "https://www.listennotes.com/c/4d3fe717742d4963a85562e9f84d8c79/",
    "publisher": "Andreessen Horowitz",
    "rss": "https://feeds.simplecast.com/JGE3yC0V",
    "thumbnail": "https://production.listennotes.com/podcasts/a16z-podcast-thumb.jpg",
    "title": "a16z Podcast",
    "total_episodes": 782,
    "update_frequency_hours": 87,
    "website": "https://a16z.com/podcasts/"
  }
}
```

### Get an episode

Get one episode's details by its Listen Notes id, including its audio URL, length, publish date, and the podcast it belongs to.

**Inputs**

- Episode ID (`episode_id`, text, required): The Listen Notes id of the episode. Search episodes first if you only have the title.

**Outputs**

- `episode` (object): The episode's details.

**Example output**

```json
{
  "episode": {
    "audio": "https://audio.listennotes.com/e/p/6b6d65930c5a4f71b254465871fed370/",
    "audio_length_sec": 2814,
    "description": "A conversation about where software is heading next.",
    "explicit_content": false,
    "id": "6b6d65930c5a4f71b254465871fed370",
    "image": "https://production.listennotes.com/podcasts/a16z-episode-image.jpg",
    "link": "https://a16z.com/podcast/the-future-of-software/",
    "listennotes_url": "https://www.listennotes.com/e/6b6d65930c5a4f71b254465871fed370/",
    "maybe_audio_invalid": false,
    "podcast_id": "4d3fe717742d4963a85562e9f84d8c79",
    "podcast_publisher": "Andreessen Horowitz",
    "podcast_title": "a16z Podcast",
    "pub_date_ms": 1706644800000,
    "thumbnail": "https://production.listennotes.com/podcasts/a16z-episode-thumb.jpg",
    "title": "The Future of Software"
  }
}
```

### Get the best podcasts

List the best podcasts as curated by Listen Notes, either overall or within one genre.

**Inputs**

- Genre ID (`genre_id`, text): Optional. A Listen Notes genre id to narrow to, for example 93 for Business. Omit for the overall best.
- Page (`page`, number): Optional. Which page of results to fetch, from 1.
- Region (`region`, text): Optional. Two-letter region code, for example "us".
- Exclude explicit podcasts (`safe_mode`, true/false): Optional. Leave out podcasts marked explicit. Off by default. Default: `false`.

**Outputs**

- `count` (number): How many podcasts this page returned.
- `genre_name` (text): The genre these are the best of, e.g. "Business".
- `has_next` (true/false): Whether another page follows.
- `page_number` (number): Which page this is.
- `podcasts` (list): The best podcasts on this page.
- `total` (number): How many podcasts exist in this genre.

**Example output**

```json
{
  "count": 1,
  "genre_name": "Business",
  "has_next": true,
  "page_number": 1,
  "podcasts": [
    {
      "country": "United States",
      "description": "The a16z Podcast discusses tech and culture trends, news, and the future, especially as 'software eats the world'.",
      "earliest_pub_date_ms": 1427212800000,
      "explicit_content": false,
      "genre_ids": [
        127,
        67,
        93
      ],
      "id": "4d3fe717742d4963a85562e9f84d8c79",
      "image": "https://production.listennotes.com/podcasts/a16z-podcast-image.jpg",
      "itunes_id": 842818711,
      "language": "English",
      "latest_pub_date_ms": 1706644800000,
      "listen_score": 78,
      "listen_score_global_rank": "0.01%",
      "listennotes_url": "https://www.listennotes.com/c/4d3fe717742d4963a85562e9f84d8c79/",
      "publisher": "Andreessen Horowitz",
      "rss": "https://feeds.simplecast.com/JGE3yC0V",
      "thumbnail": "https://production.listennotes.com/podcasts/a16z-podcast-thumb.jpg",
      "title": "a16z Podcast",
      "total_episodes": 782,
      "update_frequency_hours": 87,
      "website": "https://a16z.com/podcasts/"
    }
  ],
  "total": 4823
}
```

### Search podcasts and episodes

Full-text search across Listen Notes' podcast database. Search episodes or whole podcasts, and narrow by language, region, and explicit content.

**Inputs**

- Search query (`query`, text, required): What to search for: a topic, person, or show name, for example "star wars". Wrap in double quotes for an exact match.
- Result type (`result_type`, text): Whether to search individual episodes or whole podcasts. Defaults to episodes. One of: `episode` (Episodes), `podcast` (Podcasts). Default: `episode`.
- Offset (`offset`, number): Optional. Skip this many results, for paging. Use the next_offset from a previous run.
- Language (`language`, text): Optional. Limit to one language, for example "English".
- Region (`region`, text): Optional. Two-letter region code, for example "us".
- Exclude explicit results (`safe_mode`, true/false): Optional. Leave out podcasts and episodes marked explicit. Off by default. Default: `false`.

**Outputs**

- `count` (number): How many results this page returned.
- `next_offset` (number): Offset to pass in to fetch the next page.
- `results` (list): Matches, most relevant first. Episode-only and podcast-only fields are null on the other type.
- `total` (number): How many results exist in total.

**Example output**

```json
{
  "count": 1,
  "next_offset": 10,
  "results": [
    {
      "audio": "https://audio.listennotes.com/e/p/6b6d65930c5a4f71b254465871fed370/",
      "audio_length_sec": 2814,
      "description": "A conversation about where software is heading next.",
      "explicit_content": false,
      "id": "6b6d65930c5a4f71b254465871fed370",
      "image": "https://production.listennotes.com/podcasts/a16z-episode-image.jpg",
      "listen_score": null,
      "listennotes_url": "https://www.listennotes.com/e/6b6d65930c5a4f71b254465871fed370/",
      "podcast_id": "4d3fe717742d4963a85562e9f84d8c79",
      "podcast_title": "a16z Podcast",
      "pub_date_ms": 1706644800000,
      "publisher": null,
      "thumbnail": "https://production.listennotes.com/podcasts/a16z-episode-thumb.jpg",
      "title": "The Future of Software",
      "total_episodes": null,
      "type": "episode",
      "website": null
    }
  ],
  "total": 132
}
```