Pod Engine API v1.0

Search and Filter Podcasts

Learn how to search for podcasts using various filters and pagination

SearchPodcastsFilteringPagination
intermediate
15 minutes
PodEngine Team
Prerequisites
  • Valid API token for authentication
  • Understanding of query parameters
  • Basic knowledge of async/await and promises
1
Basic Podcast Search
Perform a simple search query for podcasts

The search endpoint allows you to find podcasts based on keywords. This is the most basic way to discover podcasts in the database.

The search algorithm looks for matches in:

  • Podcast titles
  • Podcast descriptions
  • Episode titles and descriptions
  • Host and guest names

Basic Search Request

Search for podcasts with a simple query

const options = {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_TOKEN"
  }
};

const query = "technology";
const limit = 20;

const response = await fetch(
  `http://localhost:4000/api/v1/podcasts/search?q=${query}&limit=${limit}`,
  options
);

const data = await response.json();
console.log(`Found ${data.results.length} podcasts`);
2
Advanced Filtering
Use multiple parameters to refine your search

For more precise results, you can combine multiple search parameters. This allows you to filter by category, language, and sort order.

Available filters:

  • category: Filter by podcast category (technology, business, comedy, etc.)
  • language: ISO 639-1 language code (en, es, fr, etc.)
  • sortBy: Order results by relevance, popularity, or recency
  • minEpisodes: Only show podcasts with at least N episodes
  • activeOnly: Only show currently active podcasts

Advanced Search with Filters

Combine multiple parameters for precise results

const searchParams = new URLSearchParams({
  q: "artificial intelligence",
  limit: "50",
  offset: "0",
  category: "technology",
  language: "en",
  sortBy: "relevance"
});

const options = {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_TOKEN"
  }
};

const response = await fetch(
  `http://localhost:4000/api/v1/podcasts/search?${searchParams}`,
  options
);

const data = await response.json();
3
Pagination and Bulk Retrieval
Handle large result sets with pagination

When dealing with searches that return many results, you'll need to implement pagination. The API supports offset-based pagination with a maximum limit of 100 results per request.

Best practices for pagination:

  1. Use a reasonable limit (50-100) per request
  2. Implement proper error handling for network failures
  3. Add delays between requests to avoid rate limiting
  4. Track total results to know when to stop paginating

Paginated Search Implementation

Retrieve all search results with automatic pagination

async function getAllSearchResults(query, maxResults = 1000) {
  const results = [];
  let offset = 0;
  const limit = 100;
  
  while (results.length < maxResults) {
    const searchParams = new URLSearchParams({
      q: query,
      limit: limit.toString(),
      offset: offset.toString()
    });
    
    const response = await fetch(
      `http://localhost:4000/api/v1/podcasts/search?${searchParams}`,
      options
    );
    
    const data = await response.json();
    
    if (data.results.length === 0) {
      break; // No more results
    }
    
    results.push(...data.results);
    offset += limit;
    
    // Optional: Add delay to avoid rate limiting
    await new Promise(resolve => setTimeout(resolve, 100));
  }
  
  return results;
}

const allPodcasts = await getAllSearchResults("business", 500);
console.log(`Retrieved ${allPodcasts.length} total podcasts`);