PinePods Search API Documentation
🔍 Overview
The PinePods Search API is a high-performance Rust-based Actix Web application that provides comprehensive podcast and YouTube channel discovery capabilities. The API supports multiple search providers and offers detailed content information retrieval.
✨ Key Features
- Multi-Provider Search: PodcastIndex, iTunes, and YouTube Data API v3 support
- Flexible Search Types: Search by podcast title, person/host, or YouTube channels
- Real-time Statistics: Built-in usage tracking and analytics
- High Performance: Rust-based with async processing
- CORS Enabled: Ready for web application integration
- Containerized: Docker-ready deployment
🚀 Quick Start
Prerequisites
- PodcastIndex API (Recommended): Get free API credentials
- YouTube Data API v3 (Optional): Get API key
- Docker: For containerized deployment
Environment Configuration
Create an environment file with your API credentials:
# Required for PodcastIndex searches
API_KEY=your_podcastindex_api_key
API_SECRET=your_podcastindex_api_secret
# Optional for YouTube channel searches
YOUTUBE_API_KEY=your_youtube_api_key
# Optional: Logging level
RUST_LOG=info
Docker Deployment
version: '3.8'
services:
pinepods-search-api:
image: madeofpendletonwool/pinepods_backend:latest
container_name: pinepods-search-api
env_file: .env
ports:
- "5000:5000"
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:5000/api/search"]
interval: 30s
timeout: 10s
retries: 3
PinePods Integration
Update your PinePods configuration:
# For local deployment
API_URL: 'http://localhost:5000/api/search'
# For production with domain
API_URL: 'https://your-domain.com/api/search'
📚 API Reference
Base URL
http://localhost:5000
Authentication
The API handles authentication automatically using configured environment variables. No additional authentication headers are required from clients.
🔗 Endpoints
1. Universal Search
Endpoint: GET /api/search
Description: Search for podcasts across multiple providers or YouTube channels
Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
query | string | Yes* | - | Search term or query |
index | string | No | podcastindex | Search provider: podcastindex , itunes , or youtube |
search_type | string | No | term | Search type: term or person (PodcastIndex only) |
*When both query
and index
are omitted, returns a health check response.
Provider-Specific Features
PodcastIndex (Recommended)
- Term Search:
/search/byterm
- General podcast search - Person Search:
/search/byperson
- Search by host/person name - Advanced Metadata: Rich podcast information
- Privacy Focused: No user tracking
iTunes
- Term Search Only: Basic podcast discovery
- Limited Metadata: Standard iTunes podcast data
YouTube
- Channel Search: Discover YouTube channels
- Rich Media: Thumbnails, subscriber counts, recent videos
- Real-time Data: Live statistics and content
Example Requests
# Health Check
curl -X GET 'http://localhost:5000/api/search'
# Returns: "Test connection successful"
# PodcastIndex Term Search
curl -X GET 'http://localhost:5000/api/search?query=python%20podcast&index=podcastindex'
# PodcastIndex Person Search
curl -X GET 'http://localhost:5000/api/search?query=joe%20rogan&index=podcastindex&search_type=person'
# iTunes Search
curl -X GET 'http://localhost:5000/api/search?query=tech%20news&index=itunes'
# YouTube Channel Search
curl -X GET 'http://localhost:5000/api/search?query=programming&index=youtube'
2. Podcast Details
Endpoint: GET /api/podcast
Description: Retrieve detailed information for a specific podcast using its feed ID
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | string | Yes | PodcastIndex feed ID |
Example Request
curl -X GET 'http://localhost:5000/api/podcast?id=920666'