podchaser

---
name: podchaser
description: Podchaser API for podcast data. Use when user mentions "Podchaser", "podcast",
  "podcast search", or asks about podcast information.
---

## 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`:

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

Then run:

```bash
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`:

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

Then run:

```bash
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`:

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

Then run:

```bash
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`:

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

Then run:

```bash
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`:

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

Then run:

```bash
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`:

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

Then run:

```bash
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`:

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

Then run:

```bash
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`:

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

Then run:

```bash
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`:

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

Then run:

```bash
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`:

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

Then run:

```bash
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

| Query | Description |
|-------|-------------|
| `podcast(identifier: {id: "...", type: PODCHASER})` | Get single podcast by ID |
| `podcasts(searchTerm: "...", first: N)` | Search podcasts |
| `episode(identifier: {id: "...", type: PODCHASER})` | Get single episode by ID |
| `episodes(searchTerm: "...", first: N)` | Search episodes |
| `creators(searchTerm: "...", first: N)` | Search creators/hosts |
| `networks(searchTerm: "...", first: N)` | Search podcast networks |
| `chartCategories(platform: APPLE_PODCASTS)` | List chart categories (requires paid plan) |

### Identifier Types

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

| Type | Description |
|------|-------------|
| `PODCHASER` | Podchaser internal ID |
| `APPLE_PODCASTS` | Apple Podcasts ID |
| `SPOTIFY` | Spotify ID |

### Podcast Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | ID | Unique identifier |
| `title` | String | Podcast title |
| `description` | String | Podcast description |
| `url` | String | Podcast website URL |
| `imageUrl` | String | Cover art URL |
| `language` | String | Primary language |
| `ratingAverage` | Float | Average user rating |
| `ratingCount` | Int | Number of ratings |
| `author` | Creator | Podcast author/creator |
| `categories` | [Category] | Associated categories |
| `episodes(first: N)` | EpisodeList | Podcast episodes (paginated) |

### Episode Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | ID | Unique identifier |
| `title` | String | Episode title |
| `description` | String | Episode description |
| `airDate` | Date | Publication date |
| `length` | Int | Duration in seconds |
| `url` | String | Episode URL |
| `imageUrl` | String | Episode artwork URL |
| `podcast` | Podcast | Parent podcast |

### Creator Fields

| Field | Type | Description |
|-------|------|-------------|
| `pcid` | String | Unique identifier |
| `name` | String | Creator name |
| `bio` | String | Biography |
| `imageUrl` | String | Profile image URL |
| `credits` | CreditList | Podcast appearances |

### Filter Options

| Filter | Values |
|--------|--------|
| `categories` | Category slugs |
| `language` | ISO language codes |
| `hasAppleChartRank` | Boolean |
| `hasSpotifyChartRank` | Boolean |

### Sort Options

| sortBy | Description |
|--------|-------------|
| `RELEVANCE` | Search relevance |
| `POPULARITY` | Overall popularity |
| `RATING` | User rating |
| `APPLE_CHART_RANK` | Apple ranking |
| `SPOTIFY_CHART_RANK` | Spotify ranking |
| `LATEST_EPISODE` | Most recent episode |

## 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