Listen API Docs

VERSION: V2
API de recherche et répertoire de podcasts, simple et pratique.
BASE URL: https://listen-api.listennotes.com/api/v2
Des questions? [email protected]
STATUS CODES
  • 200 success
  • 401 wrong api key or your account is suspended
  • 404 endpoint not exist, or podcast / episode not exist
  • 429 you are using FREE plan and you exceed the quota limit
  • 500 something wrong on our end

OpenAPI Spec for Listen API v2

What is OpenAPI?

"The OpenAPI Specification, originally known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services." -- Wikipedia
With the OpenAPI spec (YAML or JSON), you can use a bunch of tools to streamline your development process. For example, you can programmatically fetch and parse Listen API's entire spec using this code snippet:

1. How to get episodes of a particular podcast?

GET /podcasts/{id}. You'll get up to 10 episodes in the "episodes" field in the response. You can use the next_episode_pub_date parameter to do pagination and fetch more episodes.

2. How to implement "import OPML" and "export OPML"?

For "import OPML": POST /podcasts. You can pass up to 10 rss urls in the "rsses" parameter, and you'll get podcasts from the response.
For "export OPML": By using Listen API, you get podcast names and RSS urls from the response. and it should be straightforward to generate an OPML file.

3. How to implement a playlist for episodes?

POST /episodes. You can pass up to 10 ids in the "ids" parameter, and you'll get episodes from the response.

4. How to fetch new episodes for subscribed podcasts?

Essentially, you need to check if there are new episodes for those subscribed podcasts. The definition for "new" episodes should be personalized. For the same podcast, different users see different "new" episodes, e.g., I may have the latest 3 episodes to catch up and you may listen to every single one except for the latest episode.
There are two approaches to check if subscribed podcasts have new episodes.
Approach 1: If you want ALL new episodes for EVERY subscribed podcast...
  1. Cache the latest episode's pub_date_ms for each podcast.
  2. POST /podcasts. You can pass up to 10 ids in the "ids" parameter, and you'll get podcasts from the response. Then, you can compare latest_pub_date_ms of a podcast with the cached pub_date_ms value.
  3. GET /podcasts/{id}. For each podcast that has new episodes, fetch latest episodes. This may end up with firing multiple requests at the same time. In practice, this is not a problem, because most users don't subscribe to many podcasts and only a few podcasts have new episodes at the same time.
Approach 2: If you just need latest episodes for SOME subscribed podcasts, then just use POST /podcasts. Pass up to 10 ids in the "ids" parameter and set the show_latest_episodes parameter to 1. Then you'll get up to 10 latest episodes of these podcasts, sorted by pub_date in an descending order.

5. How to search episodes for a specific podcast?

GET /search with the "ocid" parameter (for the podcast id).

6. How to get podcasts from iTunes ids?

POST /podcasts with the "itunes_ids" parameter.

7. How to check how many requests I've used in this billing cycle?

Check the X-ListenAPI-Usage header in the response.

8. How to have multiple API tokens without creating multiple accounts?

You can create multiple apps in the API dashboard (login first). Each app has a separate API token. For example, you can have an app for dev, an app for staging, and an app for production. Or you can have apps for different developers.

9. How to get sub-genres for a particular genre?

GET /genres. You can cache the entire response data from this endpoint on the client side. Use the "parent_id" in the response to identify the hierarchical relationship among genres.