# Podcast Chart Appearances

> Pod Engine API endpoint reference, optimized for LLM consumption.
> Auto-generated from the source-of-truth endpoint registry.
>
> Category: Charts
> Source: https://www.podengine.ai/api-docs/get-podcast-chart-appearances.md
> Interactive HTML docs: https://www.podengine.ai/api-docs/get-podcast-chart-appearances
> Full API reference (all endpoints): https://www.podengine.ai/api-docs/llms.txt

**Base URL:** `https://api.podengine.ai`
**Auth:** Requires a Bearer token: `Authorization: Bearer YOUR_API_KEY`

---

#### GET /api/v1/charts/podcast-appearances
**Podcast Chart Appearances**

Get every chart a podcast is on for one date, ordered by position, with the total count

```bash
curl -X GET "https://api.podengine.ai/api/v1/charts/podcast-appearances?identityType=podcast&podcastIdOrSlug=good-hang-with-amy-poehler&chartType=apple&date=2026-09-22" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Query schema:**
```json
{
  "type": "object",
  "properties": {
    "identityType": {
      "type": "string",
      "enum": [
        "podcast",
        "platform"
      ],
      "description": "podcast: a Pod Engine podcast, given by podcastIdOrSlug. platform: one Apple or Spotify id on the chart type, given by platformId."
    },
    "podcastIdOrSlug": {
      "description": "Pod Engine podcast id or slug. Required for identityType=podcast.",
      "type": "string",
      "minLength": 1
    },
    "platformId": {
      "description": "Apple id or Spotify show id for chartType. Required for identityType=platform.",
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "chartType": {
      "type": "string",
      "enum": [
        "apple",
        "spotify"
      ],
      "description": "The type of chart, one of apple, spotify"
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "The chart date (YYYY-MM-DD)."
    },
    "limit": {
      "description": "The number of appearances to return; totalCount is unaffected.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "required": [
    "identityType",
    "date"
  ],
  "additionalProperties": false,
  "description": "Get every chart a podcast is on for one date"
}
```

**Response schema:**
```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "OK"
      ]
    },
    "data": {
      "type": "object",
      "properties": {
        "appearances": {
          "type": "object",
          "properties": {
            "podenginePodcast": {
              "nullable": true,
              "type": "object",
              "properties": {
                "author": {
                  "nullable": true,
                  "type": "string"
                },
                "authorityScore": {
                  "nullable": true,
                  "type": "object",
                  "properties": {
                    "calculatedAt": {},
                    "authorityScore": {
                      "type": "number",
                      "description": "This is the weighted total authority score of the podcast, out of 100"
                    },
                    "qualityScore": {
                      "type": "number",
                      "description": "This is the quality score of the podcast, out of 100"
                    },
                    "youtubeScore": {
                      "type": "number",
                      "description": "This is the YouTube score of the podcast, out of 100"
                    },
                    "socialScore": {
                      "type": "number",
                      "description": "This is the social score of the podcast, out of 100"
                    },
                    "engagementScore": {
                      "type": "number",
                      "description": "This is the engagement score of the podcast, out of 100"
                    }
                  },
                  "required": [
                    "calculatedAt",
                    "authorityScore",
                    "qualityScore",
                    "youtubeScore",
                    "socialScore",
                    "engagementScore"
                  ],
                  "additionalProperties": false
                },
                "genres": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "id": {
                  "type": "string"
                },
                "imageUrl": {
                  "nullable": true,
                  "type": "string"
                },
                "language": {
                  "type": "string"
                },
                "lastEpisodePublishedAt": {},
                "slug": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "titleLatest": {
                  "type": "string"
                }
              },
              "required": [
                "author",
                "authorityScore",
                "genres",
                "id",
                "imageUrl",
                "language",
                "lastEpisodePublishedAt",
                "slug",
                "title",
                "titleLatest"
              ],
              "additionalProperties": false
            },
            "podcastOnChart": {
              "nullable": true,
              "description": "The platform listing, for identityType=platform.",
              "type": "object",
              "properties": {
                "platformId": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "creator": {
                  "nullable": true,
                  "type": "string"
                },
                "imageUrl": {
                  "nullable": true,
                  "type": "string"
                }
              },
              "required": [
                "platformId",
                "title",
                "creator",
                "imageUrl"
              ],
              "additionalProperties": false
            },
            "identity": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "podcast"
                      ]
                    },
                    "podcastId": {
                      "type": "string"
                    },
                    "slug": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "podcastId",
                    "slug"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "platform"
                      ]
                    },
                    "chartType": {
                      "type": "string",
                      "enum": [
                        "apple",
                        "spotify"
                      ],
                      "description": "The type of chart, one of apple, spotify"
                    },
                    "platformId": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "chartType",
                    "platformId"
                  ],
                  "additionalProperties": false
                }
              ],
              "description": "The resolved identity, stable for deep links: the canonical Pod Engine id, or the platform id."
            },
            "chartType": {
              "type": "string",
              "enum": [
                "apple",
                "spotify"
              ],
              "description": "The type of chart, one of apple, spotify"
            },
            "date": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "The date of the chart in YYYY-MM-DD format"
            },
            "totalCount": {
              "type": "number",
              "description": "Charts the show is on that day, independent of limit."
            },
            "appearances": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "chartDate": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "description": "The date of the chart in YYYY-MM-DD format"
                  },
                  "chartType": {
                    "type": "string",
                    "enum": [
                      "apple",
                      "spotify"
                    ],
                    "description": "The type of chart, one of apple, spotify"
                  },
                  "country": {
                    "type": "string",
                    "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us."
                  },
                  "category": {
                    "type": "string",
                    "description": "The chart category defaulting to 'top podcasts'. Apple podcasts supports the following: \"top podcasts\", \"arts\", \"business\", \"comedy\", \"education\", \"fiction\", \"government\", \"health & fitness\", \"history\", \"kids & family\", \"leisure\", \"music\", \"news\", \"religion & spirituality\", \"science\", \"society & culture\", \"sports\", \"technology\", \"true crime\", \"tv & film\""
                  },
                  "position": {
                    "type": "number"
                  }
                },
                "required": [
                  "chartDate",
                  "chartType",
                  "country",
                  "category",
                  "position"
                ],
                "additionalProperties": false
              },
              "description": "Ordered by position, then country, then category."
            }
          },
          "required": [
            "podenginePodcast",
            "podcastOnChart",
            "identity",
            "chartType",
            "date",
            "totalCount",
            "appearances"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "appearances"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "status",
    "data"
  ],
  "additionalProperties": false
}
```

---

## See also

- All endpoints in one file: https://www.podengine.ai/api-docs/llms.txt
- Full reference with every schema inlined: https://www.podengine.ai/api-docs/llms-full.txt
- OpenAPI 3.1 spec: https://www.podengine.ai/api-docs/openapi.json
- Get an API key: https://www.podengine.ai/get-started
- Support: support@podengine.ai