Podchaser

Troubleshooting

If requests fail, run zero doctor check-connector --env-name PODCHASER_TOKEN or zero doctor check-connector --url https://api.podchaser.com/graphql --method POST

How to Use

1. Search Podcasts

Search for podcasts by keyword:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcasts(searchTerm: \"technology\", first: 5) { paginatorInfo { count } data { id title description author { name } } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

3. Get Podcast Details

Get detailed information about a specific podcast by ID:

Note: The type field is required in the identifier. Use PODCHASER for Podchaser IDs, APPLE_PODCASTS for Apple IDs, or SPOTIFY for Spotify IDs.

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcast(identifier: { id: \"717178\", type: PODCHASER }) { id title description url imageUrl language ratingAverage ratingCount author { name } categories { title } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

4. Search Episodes

Search for episodes across all podcasts:

Write to /tmp/podchaser_request.json:

{
  "query": "{ episodes(searchTerm: \"AI\", first: 5) { paginatorInfo { count } data { id title description airDate length podcast { title } } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

5. Get Podcast Episodes

Get episodes for a specific podcast:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcast(identifier: { id: \"717178\", type: PODCHASER }) { id title episodes(first: 10) { data { id title description airDate length } } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

6. Get Episode Details

Get detailed information about a specific episode:

Write to /tmp/podchaser_request.json:

{
  "query": "{ episode(identifier: { id: \"789012\", type: PODCHASER }) { id title description airDate length url imageUrl podcast { id title } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

7. Get Podcast Categories

Categories are available as a field on podcast objects. Get categories for a specific podcast:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcast(identifier: { id: \"717178\", type: PODCHASER }) { title categories { title slug } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

8. Filter Podcasts by Category

Get podcasts in a specific category:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcasts(filters: { categories: [\"technology\"] }, first: 10) { data { id title description ratingAverage } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

9. Get Chart Rankings

Get Apple Podcasts chart data:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcasts(filters: { hasAppleChartRank: true }, sort: { sortBy: APPLE_CHART_RANK, direction: ASC }, first: 10) { data { id title appleChartRank } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

10. Get Creator/Host Information

Search for podcast creators:

Write to /tmp/podchaser_request.json:

{
  "query": "{ creators(searchTerm: \"Joe Rogan\", first: 5) { data { pcid name bio credits { data { podcast { title } } } } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

11. Preview Query Cost

Check how many points a query will cost before executing:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcasts(searchTerm: \"tech\", first: 10) { data { id title description episodes(first: 5) { data { id title } } } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql/cost" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

GraphQL Schema Reference

Main Queries

Identifier Types

The type field is required when using identifier to fetch a podcast or episode:

Podcast Fields

Episode Fields

Creator Fields

Filter Options

Sort Options

Rate Limits

• Request Limit: 50 requests per 10 seconds
• Points System: Query cost based on fields returned
• Response Headers:
• X-Podchaser-Points-Remaining: Available points
• X-Podchaser-Query-Cost: Points consumed

Example costs:

• Basic podcast metadata: ~9 points
• Search 10 podcasts with details: ~100 points

Guidelines

1. Store Access Token: Tokens last 1 year, avoid requesting new tokens for each query 2. Preview Costs: Use /graphql/cost endpoint to estimate query cost before execution 3. Use Limited Scope: For client-side apps, request tokens with limited_scope: true (1 hour expiry) 4. Optimize Queries: Request only needed fields to minimize points consumption 5. Handle Rate Limits: Check Retry-After header on 429 responses 6. Security: Never expose regular access tokens in client-side code