Podcast-api NPM

Podcast API JavaScript Library

The Podcast API JavaScript library provides convenient access to the Listen Notes Podcast API from applications written in JavaScript, including

Server-side Node.js: See example code PodcastAppForNode
Serverless Cloudflare Workers / Cloudflare Pages (w/ functions): See example code PodcastAppForWorkers
Client-side Javascript in web browsers: See example code PodcastAppForBrowser

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.

Note: We don't recommend using our Podcast API in client-side JavaScript in the browser, because it'll leak your API key in the code.

If you have any questions, please contact hello@listennotes.com

Table of Contents

Podcast API JavaScript Library

Installation

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

npm install podcast-api --save
# or
yarn add podcast-api

Requirements

Node 18 or higher

Usage

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

// If you use our Podcast API with Node.js or browser javascript, then use the Client class.
const { Client } = require('podcast-api');
const client = Client({
  apiKey: process.env.LISTEN_API_KEY || null,
});

// If you use our Podcast API with Cloudflare Workers / Pages, then use the ClientForWorkers class.
// Please make sure you store LISTEN_API_KEY as a secret. See example code: 
//   - https://github.com/ListenNotes/podcast-api-js/blob/main/examples/PodcastAppForWorkers/src/index.js
// const { ClientForWorkers } = require('podcast-api');
// const client = ClientForWorkers({
//  apiKey: env.LISTEN_API_KEY || null,
// });


client.search({
  q: 'elon musk',
}).then((response) => {
  console.log(response.data);
}).catch((error) => {
  if (error.response) {
    switch (error.response.status) {
      case 404:
        // Endpoint not exist or podcast / episode not exist
        break;
      case 401:
        // Wrong API key, or your account is suspended
        break;
      case 400:
        // Invalid parameters
        break;
      case 500:
        // Server-side error
        break;
      default:
        // Unknown errors
        break;
    }
  } else {
    // Failed to connect to Listen API servers
  }
  console.log(error);
});

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

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:

const { Client } = require('podcast-api');

// If api_key is null, the sdk will connect to a mock server that'll
// return fake data for testing purpose
const client = Client({
  apiKey: process.env.LISTEN_API_KEY || null,
});

client.search({ q: 'elon musk', sort_by_date: 1, only_in: 'title,description' }).then((response) => {
  console.log(response.data);
}).catch((error) => {
  console.log(error);
});

See all available parameters on the API Docs page.

Typeahead search

Function Name: typeahead

Suggest search terms, podcast genres, and podcasts.

Example:

const { Client } = require('podcast-api');

// If api_key is null, the sdk will connect to a mock server that'll
// return fake data for testing purpose
const client = Client({
  apiKey: process.env.LISTEN_API_KEY || null,
});

client.typeahead({ q: 'startup', show_podcasts: 1 }).then((response) => {
  console.log(response.data);
}).catch((error) => {
  console.log(error);
});

See all available parameters on the API Docs page(https://www.listennotes.com/api/docs/#get-api-v2-typeah