{"id":16878,"library":"podcast-api","title":"Listen Notes Podcast API JavaScript Library","description":"The `podcast-api` library provides convenient JavaScript bindings for the Listen Notes Podcast API, enabling developers to search, retrieve, and manage podcast and episode metadata programmatically. It supports a wide range of environments, including server-side Node.js applications, serverless Cloudflare Workers/Pages, and client-side browser JavaScript, although browser usage is discouraged without proper API key handling to prevent exposure. The current stable version is 2.0.4, with active development indicated by frequent releases introducing new endpoints like `searchEpisodeTitles` and `fetchPodcastsByDomain`. A key differentiator is its dual client architecture, offering `Client` for Node.js/browser environments and `ClientForWorkers` specifically optimized for Cloudflare Workers, providing streamlined access to the same API that powers the Listen Notes search engine.","status":"active","version":"2.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/ListenNotes/podcast-api-js","tags":["javascript","Listen Notes","podcast","api","podcast search","search engine","Cloudflare Workers","Node.js"],"install":[{"cmd":"npm install podcast-api","lang":"bash","label":"npm"},{"cmd":"yarn add podcast-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add podcast-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Use named import for ESM. For CommonJS, `require` returns an object with named exports, so destructuring `const { Client } = require('podcast-api');` is correct. Trying to instantiate the entire `require` result directly as `Client` is incorrect.","wrong":"const Client = require('podcast-api');","symbol":"Client","correct":"import { Client } from 'podcast-api';\nconst client = Client({ apiKey: process.env.LISTEN_API_KEY ?? '' });"},{"note":"This client is specifically designed for Cloudflare Workers and assumes `LISTEN_API_KEY` is available as a secret in the Worker's scope. While a CommonJS `require` might technically work in some build environments for Workers, ESM `import` is the idiomatic and recommended approach for Cloudflare Workers.","wrong":"const { ClientForWorkers } = require('podcast-api');","symbol":"ClientForWorkers","correct":"import { ClientForWorkers } from 'podcast-api';\nconst client = ClientForWorkers({ apiKey: LISTEN_API_KEY });"},{"note":"This is the recommended CommonJS pattern for Node.js and browser environments. Ensure `LISTEN_API_KEY` is securely managed via environment variables.","symbol":"Client","correct":"const { Client } = require('podcast-api');\nconst client = Client({ apiKey: process.env.LISTEN_API_KEY ?? '' });"}],"quickstart":{"code":"import { Client } from 'podcast-api';\n\n// Initialize the client with your API key.\n// For Node.js, use process.env.LISTEN_API_KEY.\n// For Cloudflare Workers, use LISTEN_API_KEY from secrets.\n// For browser-side, handle key securely (e.g., via a proxy).\nconst apiKey = process.env.LISTEN_API_KEY ?? 'YOUR_LISTEN_NOTES_API_KEY'; // Replace or ensure env var is set\n\nif (!apiKey || apiKey === 'YOUR_LISTEN_NOTES_API_KEY') {\n  console.error('API Key is missing. Please set LISTEN_API_KEY environment variable or replace the placeholder.');\n  process.exit(1);\n}\n\nconst client = Client({ apiKey });\n\nasync function searchPodcasts(query) {\n  try {\n    const response = await client.search({\n      q: query,\n      sort_by: 'relevance',\n      type: 'podcast',\n      offset: 0,\n      len_min: 10,\n      len_max: 30,\n      genre_ids: '68,82',\n      published_before: 1580172454000,\n      published_after: 0,\n      only_in: 'title,description',\n      language: 'English',\n      safe_mode: 0\n    });\n    console.log(`Found ${response.data.total} podcasts for \"${query}\":`);\n    response.data.results.slice(0, 3).forEach(podcast => {\n      console.log(`- ${podcast.title_original} (ID: ${podcast.id})`);\n    });\n  } catch (error) {\n    console.error('Error searching podcasts:', error.message);\n  }\n}\n\n// Example usage\nsearchPodcasts('web development');","lang":"typescript","description":"This quickstart initializes the `podcast-api` client and demonstrates a basic full-text search for podcasts, logging the results. It highlights API key configuration and error handling."},"warnings":[{"fix":"Proxy requests through your own backend server or a serverless function (like Cloudflare Workers) to keep your API key secure.","message":"Directly using the Podcast API client with an exposed API key in client-side browser JavaScript is strongly discouraged. This can lead to your API key being compromised.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For Node.js or browser, use `import { Client } from 'podcast-api';`. For Cloudflare Workers, use `import { ClientForWorkers } from 'podcast-api';` and ensure your API key is stored as a Worker secret.","message":"Two distinct client classes exist: `Client` for Node.js/browser environments and `ClientForWorkers` for Cloudflare Workers/Pages functions. Using the wrong client can lead to unexpected behavior or errors, especially concerning API key handling.","severity":"gotcha","affected_versions":">=2.0.1"},{"fix":"Ensure your Node.js environment is updated to version 10 or newer. Check your `node` version using `node -v`.","message":"The library requires Node.js version 10 or higher. Running it on older Node.js versions may result in compatibility issues or runtime errors.","severity":"gotcha","affected_versions":"<=1.x"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Initialize the client with `Client({ apiKey: 'YOUR_API_KEY' })` or ensure your `LISTEN_API_KEY` environment variable is correctly configured and accessible in your application's environment.","cause":"The `apiKey` parameter was not provided during client initialization, or the `process.env.LISTEN_API_KEY` (or `LISTEN_API_KEY` for Workers) environment variable was not set.","error":"API key is missing"},{"fix":"Ensure you are using named imports for ESM (`import { Client } from 'podcast-api';`) or destructuring for CommonJS (`const { Client } = require('podcast-api');`). Do not attempt `import Client from 'podcast-api';` or `const Client = require('podcast-api'); Client(...)`.","cause":"This error often occurs in environments using module bundlers or transpilers when a default import is attempted for a library that only provides named exports, or when CommonJS `require` is used and then the result is incorrectly called directly as a function.","error":"TypeError: (0 , podcast_api__WEBPACK_IMPORTED_MODULE_0__.Client) is not a function"}],"ecosystem":"npm","meta_description":null}