Integrating PodPeopleDB Into Your App

API Documentation

Available Endpoints

Get Podcast Information

GET /api/podcast/{id}

Returns podcast details and host information for a specific podcast using the Podcast Index Feed ID. Includes both podcast-level hosts and any Podcast 2.0 person tags from the feed.

Get Episodes for a Podcast

GET /api/podcast/{id}/episodes

Returns episodes for a specific podcast, including guest information and episode-level person data from Podcast 2.0 feeds. Supports optional limit parameter (default: 20, max: 100).

Get Host Details

GET /api/hosts/{id}

Returns detailed information about hosts associated with a podcast.

Download Full Database

GET /api/download-database

Downloads the entire SQLite database for offline use.

Get Public Dataset

GET /api/public-dataset

Downloads a JSON export of all public data including hosts, podcasts, episodes, and guest relationships.

Additional Endpoints

GET /api/recent-hosts

Returns recently added hosts.

GET /api/search-podcasts?query={term}

Search for podcasts by name.

GET /api/stats

Returns database statistics.

GET /api/popular-podcasts

Returns popular podcasts based on host count.

Database Schema

The SQLite database includes the following main tables:

-- Hosts and Guests
CREATE TABLE hosts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT,
    description TEXT,
    link TEXT,
    img TEXT,
    created_at DATETIME
);

-- Podcast-Host relationships
CREATE TABLE host_podcasts (
    host_id INTEGER,
    podcast_id INTEGER,
    role TEXT,
    status TEXT,
    created_at DATETIME
);

-- Episodes
CREATE TABLE episodes (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    podcast_id INTEGER,
    title TEXT,
    description TEXT,
    audio_url TEXT UNIQUE,
    pub_date DATETIME,
    duration INTEGER,
    season_number INTEGER,
    episode_number INTEGER,
    image_url TEXT,
    link TEXT,
    guid TEXT,
    status TEXT,
    created_at DATETIME
);

-- Episode-Guest relationships
CREATE TABLE episode_guests (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    episode_id INTEGER,
    host_id INTEGER,
    role TEXT,
    status TEXT,
    approval_key TEXT,
    approval_key_expires_at DATETIME,
    created_at DATETIME
);

Example Integration

Getting Podcast Hosts

// Get podcast information including hosts
async function getPodcastHosts(podcastId) {
    const response = await fetch(`https://podpeople.db/api/podcast/${podcastId}`);
    const data = await response.json();
    return data.hosts; // Array of hosts from Podcast 2.0 or database
}

Getting Episode Guests

// Get episodes with guest information
async function getEpisodesWithGuests(podcastId, limit = 20) {
    const response = await fetch(`https://podpeople.db/api/podcast/${podcastId}/episodes?limit=${limit}`);
    const episodes = await response.json();
    
    // Each episode includes:
    // - episode.guests: array of approved guests
    // - episode.can_add_guests: boolean if submissions allowed
    // - episode.guest_count: number of guests
    return episodes;
}

Directing Users to Episode Pages

// Generate episode page URLs for guest submissions
function getEpisodePageUrl(podcastId, audioUrl) {
    const encodedAudioUrl = encodeURIComponent(audioUrl);
    return `https://podpeople.db/episode/${podcastId}/${encodedAudioUrl}`;
}

// Example: Create a "Submit Guest" button
function createSubmitGuestButton(episode, podcastId) {
    if (!episode.can_add_guests) return null; // No submissions allowed
    
    const button = document.createElement('a');
    button.href = getEpisodePageUrl(podcastId, episode.audio_url);
    button.textContent = 'Submit Guest Information';
    button.target = '_blank';
    return button;
}

Complete Example

// Complete integration example
async function displayPodcastWithEpisodes(podcastId) {
    try {
        // Get podcast info
        const podcastResponse = await fetch(`https://podpeople.db/api/podcast/${podcastId}`);
        const podcast = await podcastResponse.json();
        
        // Get episodes
        const episodesResponse = await fetch(`https://podpeople.db/api/podcast/${podcastId}/episodes`);
        const episodes = await episodesResponse.json();
        
        // Display podcast hosts
        console.log('Podcast Hosts:', podcast.hosts);
        
        // Display episodes with guests
        episodes.forEach(episode => {
            console.log(`Episode: ${episode.title}`);
            console.log(`Guests:`, episode.guests);
            
            if (episode.can_add_guests) {
                const episodeUrl = getEpisodePageUrl(podcastId, episode.audio_url);
                console.log(`Guest submission URL: ${episodeUrl}`);
            }
        });
        
    } catch (error) {
        console.error('Error fetching data:', error);
    }
}

Episode Guest Functionality

PodPeopleDB supports episode-level guest tracking with the following features:

Podcast 2.0 Compatibility

Manual Guest Submissions

For podcasts without Podcast 2.0 tags, users can submit episode guests:

URL Structure

// Podcast page (hosts and episodes list)
https://podpeople.db/podcast/{podcastId}

// Episode page (episode details and guests)
https://podpeople.db/episode/{podcastId}/{encodedAudioUrl}

// Example episode URL
https://podpeople.db/episode/123456/https%3A%2F%2Fexample.com%2Fepisode.mp3

Integration Best Practices

Rate Limits

Currently, there are no rate limits in place, but please be considerate with your API usage.

Next: Self-Host PodPeopleDB →