@mj-kiwi/podcast-index-api

A TypeScript client for the Podcast Index API.

Features

• Full TypeScript support with comprehensive type definitions
• Promise-based API client
• Automatic authentication handling
• Complete implementation of all major API endpoints
• Robust test coverage

Installation

# Using npm
npm install @mj-kiwi/podcast-index-api

# Using yarn
yarn add @mj-kiwi/podcast-index-api

# Using pnpm
pnpm add @mj-kiwi/podcast-index-api

Authentication

To use the API, you'll need to register for API credentials at api.podcastindex.org. Once you have your API key and secret, you can initialize the client:

import { PodcastIndexClient } from '@mj-kiwi/podcast-index-api';

const client = new PodcastIndexClient({
  authKey: 'your-auth-key',
  secretKey: 'your-secret-key',
  // Optional configuration
  userAgent: 'YourApp/1.0',  // Default: PodcastIndexTS/1.0
  baseUrl: 'https://api.podcastindex.org/api/1.0'  // Default URL
});

Usage Examples

Search for Podcasts

// Search podcasts by term
const searchResults = await client.searchPodcasts({ 
  q: 'tech news',
  clean: true,
  max: 20
});

// Search podcasts by title
const titleResults = await client.searchPodcastsByTitle({ 
  q: 'daily tech news' 
});

// Search episodes by person
const personResults = await client.searchEpisodesByPerson({ 
  q: 'Adam Curry' 
});

Get Podcast Information

// Get podcast by feed ID
const podcast = await client.getPodcastByFeedId({ id: 920666 });

// Get podcast by feed URL
const podcastByUrl = await client.getPodcastByFeedUrl({ 
  url: 'https://feeds.example.com/podcast.xml' 
});

// Get podcast by iTunes ID
const podcastByItunes = await client.getPodcastByItunesId({ id: 1441923632 });

// Get podcast by GUID
const podcastByGuid = await client.getPodcastByGuid({ 
  guid: '917393e3-1b1e-5cef-ace4-edaa54e1f810' 
});

Get Episode Information

// Get episodes by feed ID
const episodes = await client.getEpisodesByFeedId({ 
  id: 920666,
  max: 10,
  fulltext: true
});

// Get recent episodes
const recentEpisodes = await client.getRecentEpisodes({ max: 20 });

// Get episodes by GUID
const episodeByGuid = await client.getEpisodesByGuid({
  guid: 'episode-guid',
  feedid: 920666
});

Value for Value Information

// Get value info by feed ID
const valueInfo = await client.getValueByFeedId({ id: 920666 });

// Get value info by feed URL
const valueByUrl = await client.getValueByFeedUrl({ 
  url: 'https://feeds.example.com/podcast.xml' 
});

Get Stats and Categories

// Get current stats
const stats = await client.getStats();

// Get categories list
const categories = await client.getCategories();

API Documentation

Search Endpoints

Method	Description
searchPodcasts()	Search podcasts by term in title, author or owner
searchPodcastsByTitle()	Search podcasts by title only
searchEpisodesByPerson()	Search episodes mentioning a person

Podcast Endpoints

Method	Description
getPodcastByFeedId()	Get podcast info by feed ID
getPodcastByFeedUrl()	Get podcast info by feed URL
getPodcastByGuid()	Get podcast info by GUID
getPodcastByItunesId()	Get podcast info by iTunes ID
getPodcastsByMedium()	Get podcasts by medium type

Episode Endpoints

Method	Description
getEpisodesByFeedId()	Get episodes by feed ID
getEpisodesByFeedUrl()	Get episodes by feed URL
getEpisodesByGuid()	Get episodes by GUID
getEpisodesByItunesId()	Get episodes by iTunes ID
getRecentEpisodes()	Get recent episodes

Value Endpoints

Method	Description
getValueByFeedId()	Get value info by feed ID
getValueByFeedUrl()	Get value info by feed URL

Other Endpoints

Method	Description
getStats()	Get current index statistics
getCategories()	Get list of podcast categories

Development

Setup

# Install dependencies
pnpm install

# Build the package
pnpm build

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Build type declarations
pnpm build:types

Testing

The project uses Vitest for testing. Tests are located in the test/ directory.

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage report
pnpm test:coverage

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.