Download the PHP package listennotes/podcast-api without Composer

Podcast API PHP Library

The Podcast API PHP library provides convenient access to the Listen Notes Podcast API from applications written in the PHP language.

Simple and no-nonsense podcast search & directory API. Search the meta data of all podcasts and episodes by people, places, or topics. It's the same API that powers the best podcast search engine Listen Notes.

If you have any questions, please contact [email protected]

Table of Contents

• Podcast API PHP Library
  • Installation
  • Requirements
  • Usage
  • Handling exceptions
  • API Reference
  • Full-text search
  • Typeahead search
  • Fetch detailed meta data and episodes for a podcast by id
  • Fetch detailed meta data for an episode by id
  • Fetch a list of supported languages for podcasts
  • Fetch a list of podcast genres
  • Fetch a list of best podcasts by genre
  • Fetch a list of supported countries/regions for best podcasts
  • Fetch recommendations for a podcast
  • Fetch recommendations for an episode
  • Batch fetch basic meta data for episodes
  • Batch fetch basic meta data for podcasts
  • Fetch a random podcast episode
  • Fetch a curated list of podcasts by id
  • Fetch curated lists of podcasts
  • Submit a podcast to Listen Notes database
  • Request to delete a podcast
  • Fetch a playlist's info and items (i.e., episodes or podcasts).
  • Fetch a list of your playlists.
  • Fetch trending search terms
  • Fetch related search terms
  • Spell check on a search term
  • Fetch audience demographics for a podcast
  • Fetch podcasts by a publisher's domain name
  • Find individual episodes by searching for their titles

Installation

Install the official Composer package of the Listen Notes Podcast API:

To use the bindings, use Composer's autoload:

Requirements

• PHP 7.3+

Usage

The library needs to be configured with your account's API key which is available in your Listen API Dashboard. Set API_KEY to its value:

If API_KEY is null, then we'll connect to a mock server that returns fake data for testing purposes.

Handling exceptions

Unsuccessful requests raise exceptions. The class of the exception will reflect the sort of error that occurred.

All exception classes can be found in this folder.

And you can see some sample code here.

API Reference

Each function is a wrapper to send an HTTP request to the corresponding endpoint on the API Docs.

Full-text search

Function Name: search

Full-text search on episodes, podcasts, or curated lists of podcasts. Use the offset parameter to paginate through search results. The FREE plan allows to see up to 30 search results (or offset < 30) per query. The PRO plan allows to see up to 300 search results (or offset < 300) per query. The ENTERPRISE plan allows to see up to 10,000 search results (or offset < 10000) per query.

Example:

See all available parameters on the API Docs page.

Typeahead search

Function Name: typeahead

Suggest search terms, podcast genres, and podcasts.

Example:

See all available parameters on the API Docs page.

Fetch detailed meta data and episodes for a podcast by id

Function Name: getPodcastById

Fetch detailed meta data and episodes for a specific podcast (up to 10 episodes each time). You can use the next_episode_pub_date parameter to do pagination and fetch more episodes.

Example:

See all available parameters on the API Docs page.

Fetch detailed meta data for an episode by id

Function Name: fetchEpisodeById

Fetch detailed meta data for a specific episode.

Example:

See all available parameters on the API Docs page.

Fetch a list of supported languages for podcasts

Function Name: fetchPodcastLanguages

Get a list of languages that are supported in Listen Notes database. You can use the language string as query parameter in GET /search.

Example:

See all available parameters on the API Docs page.

Fetch a list of podcast genres

Function Name: fetchPodcastGenres

Get a list of podcast genres that are supported in Listen Notes. The genre id can be passed to other endpoints as a parameter to get podcasts in a specific genre, e.g., GET /best_podcasts, GET /search... You may want to cache the list of genres on the client side.

Example:

See all available parameters on the API Docs page.

Fetch a list of best podcasts by genre

Function Name: fetchBestPodcasts

Get a list of curated best podcasts by genre, which are curated by Listen Notes staffs based on various signals from the Internet, e.g., top charts on other podcast platforms, recommendations from mainstream media, user activities on listennotes.com... You can get the genre ids from GET /genres endpoint. This endpoint returns same data as https://www.listennotes.com/best-podcasts/

Example:

See all available parameters on the API Docs page.

Fetch a list of supported countries/regions for best podcasts

Function Name: fetchPodcastRegions

It returns a dictionary of country codes (e.g., us, gb...) & country names (United States, United Kingdom...). The country code is used in the query parameter region of GET /best_podcasts.

Example:

See all available parameters on the API Docs page.

Fetch recommendations for a podcast

Function Name: fetchRecommendationsForPodcast

Fetch up to 8 podcast recommendations based on the given podcast id.

Example:

See all available parameters on the API Docs page.

Fetch recommendations for an episode

Function Name: fetchRecommendationsForEpisode

Fetch up to 8 episode recommendations based on the given episode id.

Example:

See all available parameters on the API Docs page.

Batch fetch basic meta data for episodes

Function Name: batchFetchEpisodes

Batch fetch basic meta data for up to 10 episodes. This endpoint could be used to implement custom playlists for individual episodes. For detailed meta data of an individual episode, you need to use GET /episodes/{id}. This endpoint is available only in the PRO/ENTERPRISE plan.

Example:

See all available parameters on the API Docs page.

Batch fetch basic meta data for podcasts

Function Name: batchFetchPodcasts

Batch fetch basic meta data for up to 10 podcasts. This endpoint could be used to build something like OPML import, allowing users to import a bunch of podcasts via rss urls. For detailed meta data (including episodes) of an individual podcast, you need to use GET /podcasts/{id}. This endpoint is available only in the PRO/ENTERPRISE plan.

Example:

See all available parameters on the API Docs page.

Fetch a random podcast episode

Function Name: justListen

Recently published episodes are more likely to be fetched. Good luck!

Example:

See all available parameters on the API Docs page.

Fetch a curated list of podcasts by id

Function Name: fetchCuratedPodcastsListById

Get detailed meta data of all podcasts in a specific curated list. This endpoint returns same data as https://www.listennotes.com/curated-podcasts/

Example:

See all available parameters on the API Docs page.

Fetch curated lists of podcasts

Function Name: fetchCuratedPodcastsLists

A bunch of curated lists from online media. For each list, you'll get basic info of up to 5 podcasts. To get detailed meta data of all podcasts in a specific list, you need to use GET /curated_podcasts/{id}. We add new curated lists to the database on a daily basis.

Example:

See all available parameters on the API Docs page.

Submit a podcast to Listen Notes database

Function Name: submitPodcast

Podcast hosting services can use this endpoint to help your users directly submit a new podcast to Listen Notes database. If the podcast doesn't exist in the database, "status" in the response will be "in review", and we'll review it within 12 hours. If the podcast exists, "status" in the response will be "found". If this submission is rejected, "status" in the response will be "rejected". You can use POST /podcasts to check if multiple podcasts exist in the database. If you want to get a notification once the podcast is accepted, you can either specify the "email" parameter or configure a webhook url in the dashboard: listennotes.com/api/dashboard/#webhooks

Example:

See all available parameters on the API Docs page.

Request to delete a podcast

Function Name: deletePodcast

Podcast hosting services can use this endpoint to streamline the process of podcast deletion on behave of their users (podcasters). We will review the deletion request within 12 hours. If the podcast is already deleted, the "status" field in the response will be "deleted". Otherwise, the status field will be "in review". If you want to get a notification once the podcast is deleted, you can configure a webhook url in the dashboard: listennotes.com/api/dashboard/#webhooks

Example:

See all available parameters on the API Docs page.

Fetch a playlist's info and items (i.e., episodes or podcasts).

Function Name: fetchPlaylistById

A playlist can be an episode list (i.e., all items are episodes) or a podcast list (i.e., all items are podcasts), which is essentially the same as those created via listennotes.com/listen/. This endpoint fetches a list of items (i.e., episodes or podcasts) in the playlist. You can use the last_pub_date_ms parameter to do pagination and fetch more items. A playlist can be public (discoverable on ListenNotes.com), unlisted (accessible to anyone who knows the playlist id), or private (accessible to its owner). You can fetch all playlists created by you, and public / unlisted playlists created by others.

Example:

See all available parameters on the API Docs page.

Fetch a list of your playlists.

Function Name: fetchMyPlaylists

This endpoint returns same data as listennotes.com/listen under your account. You can use the page parameter to do pagination and fetch more playlists.

Example:

See all available parameters on the API Docs page.

Fetch trending search terms

Function Name: fetchTrendingSearches

Fetch up to 10 most recent trending search terms on the Listen Notes platform.

Example:

See all available parameters on the API Docs page.

Fetch related search terms

Function Name: fetchRelatedSearches

Suggest related search terms. The results are more comprehensive than from GET /typeahead. This endpoint is available only in the PRO/ENTERPRISE plan.

Example:

See all available parameters on the API Docs page.

Spell check on a search term

Function Name: spellcheck

Suggest a list of words that correct the spelling errors of a search term. This endpoint is available only in the PRO/ENTERPRISE plan.

Example:

See all available parameters on the API Docs page.

Fetch audience demographics for a podcast

Function Name: fetchAudienceForPodcast

Fetch audience demographics for a podcast - 1) directly measured on the Listen Notes platform; 2) only supports audience breakdown by regions for now; 3) not every podcast has data.

Example:

See all available parameters on the API Docs page.

Fetch podcasts by a publisher's domain name

Function Name: fetchPodcastsByDomain

Fetch podcasts by a publisher's domain name, e.g., nytimes.com, wondery.com, npr.org... Each request will return up to 10 podcasts. You can use the page parameter to paginate.

Example:

See all available parameters on the API Docs page.

Find individual episodes by searching for their titles

Function Name: searchEpisodeTitles

Conduct targeted searches for individual episodes by title and refine results using the podcast id such as Listen Notes Podcast ID, Apple Podcasts ID, Spotify ID, or RSS feed URL. This endpoint is specially designed to streamline the import of specific episodes from platforms like Apple Podcasts and Spotify into your application. Compared to the GET /search endpoint, which performs full-text searches across multiple fields, this endpoint focuses solely on episode titles for enhanced accuracy and performance.

Example:

See all available parameters on the API Docs page.