podcastic/PODCAST_INDEX_SETUP.md

🔍 Podcast Index Integration Setup

This guide explains how to set up Podcast Index API for podcast discovery and search functionality in Podcastic.

What is Podcast Index?

Podcast Index is a free, independent podcast database and API that provides:

• Podcast search functionality
• Trending podcasts
• Podcast metadata (title, author, image, description)
• Episode information
• No ads, no corporate tracking

Prerequisites

• Podcastic backend running
• Internet connection
• Free Podcast Index account

Step 1: Get API Keys

Register on Podcast Index

1. Visit Podcast Index API
2. Click "Sign Up" (top right)
3. Create a free account with your email
4. Check your email for verification link
5. Confirm your email address

Generate API Keys

1. Log in to your Podcast Index account
2. Go to "My API Keys" section
3. You'll see:
   • API Key (e.g., abcdef123456)
   • API Secret (e.g., xyz789)
4. Copy both values

Step 2: Configure Environment Variables

Update .env file

# In the root Podcastic directory
nano .env  # or edit with your preferred editor

Add these lines:

PODCAST_INDEX_API_KEY=your_api_key_here
PODCAST_INDEX_API_SECRET=your_api_secret_here

Example:

PODCAST_INDEX_API_KEY=abcdef123456
PODCAST_INDEX_API_SECRET=xyz789opqrst

Docker Setup

If using Docker, the environment variables will be automatically loaded from .env:

docker-compose up -d

The backend will automatically detect and use your API keys.

Step 3: Verify Setup

Test API Integration

# Start the backend (if not running)
cd backend
npm run dev

# In another terminal, test the API
curl http://localhost:5000/api/podcasts/discover?q=technology

Expected response:

{
  "source": "podcastindex",
  "podcasts": [
    {
      "id": "25566",
      "title": "Example Podcast",
      "rssUrl": "https://example.com/feed",
      "author": "Podcast Author",
      "description": "...",
      "imageUrl": "...",
      "episodeCount": 150
    }
  ],
  "count": 10
}

Test in Frontend

1. Open http://localhost:3000/discover
2. Click on the "🔍 Search Results" tab
3. Type a podcast name (e.g., "technology", "news", "music")
4. Results should appear from Podcast Index

Features Enabled by API

✅ Podcast Discovery

• Search by keyword
• Browse trending podcasts
• View podcast metadata

✅ Quick Subscribe

• Find podcasts directly from discover page
• One-click subscribe
• Auto-fetch episodes

Example Searches

• Popular podcasts: "Joe Rogan", "NPR", "BBC"
• Topics: "technology", "news", "business", "science"
• Specific shows: "The Daily", "Serial", "Freakonomics"

API Limits

Free Tier (Default)

• 100 requests per minute per API key
• Sufficient for small to medium users
• No additional signup needed

If You Need More

• Podcast Index offers higher rate limits for supporters
• See their pricing page for details

Fallback When API is Unavailable

If PodcastIndex API is not configured or unavailable:

• Users can still subscribe manually using RSS URLs
• Dashboard shows previously subscribed podcasts
• Graceful degradation - app still works

Troubleshooting

"API credentials not configured"

Solution: Check that both PODCAST_INDEX_API_KEY and PODCAST_INDEX_API_SECRET are set in .env

# Verify environment variables
echo $PODCAST_INDEX_API_KEY
echo $PODCAST_INDEX_API_SECRET

"Search rate limited"

Error: Search rate limited. Please try again later.

Solution:

• Wait a minute before searching again
• Rate limit resets every 60 seconds
• This is normal with free tier - switch searches if needed

"Authentication failed"

Error: PodcastIndex API authentication failed

Solution:

• Verify your API keys are correct
• Check for extra spaces/newlines in .env
• Regenerate API keys on Podcast Index website if needed

No results appear

Possible causes:

• API key not configured
• Internet connection issue
• Podcast doesn't exist in Podcast Index database

Solution:

• Try a very common podcast name first (e.g., "NPR")
• Check your internet connection
• Fall back to subscribing via RSS URL if needed

Security Notes

⚠️ Important

• Never commit .env to git (it's in .gitignore)
• Don't share your API secret publicly
• API keys are for your use only
• Regenerate keys if accidentally exposed

Using RSS URLs as Alternative

If you don't want to use Podcast Index:

1. Find podcast RSS URL:

   • On the podcast's website
   • Search "[Podcast Name] RSS" in Google
   • Common format: example.com/feed or example.com/podcast/rss

2. Subscribe directly:

   • Go to Dashboard
   • Click Subscribe (or future manual add feature)
   • Paste RSS URL
   • Podcastic fetches episodes automatically

API Documentation

Full API reference: Podcast Index Documentation

Key endpoints available in Podcastic:

• GET /api/podcasts/discover - Search podcasts
• GET /api/podcasts/trending - Get trending podcasts
• POST /api/podcasts/subscribe-discovery - Subscribe from search results

Advanced: Custom Podcast Sources

To use a different podcast database:

1. Implement a new service in backend/src/services/
2. Add environment variables for API credentials
3. Update podcastController.ts to use the new service
4. No frontend changes needed!

Example: Could integrate Apple Podcasts API, Spotify API, or self-hosted podcast database.

Support

• Podcast Index Support: https://podcastindex.org/contact
• Podcastic Issues: Create an issue on GitHub
• RSS Feed Help: See GETTING_STARTED.md for manual subscription

---

Last Updated: 2026-04-16
Podcast Index Status: https://podcastindex.org/status