# Podcast Chart History

> 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-history.md
> Interactive HTML docs: https://www.podengine.ai/api-docs/get-podcast-chart-history
> 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-history
**Podcast Chart History**

Get a podcast's rank history on one chart: daily ranks for 30 or 90 days, weekly buckets for longer ranges, with range stats and coverage gaps

```bash
curl -X GET "https://api.podengine.ai/api/v1/charts/podcast-history?identityType=podcast&podcastIdOrSlug=good-hang-with-amy-poehler&category=top+podcasts&chartType=apple&country=us&range=30d" \
  -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"
    },
    "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\""
    },
    "country": {
      "type": "string",
      "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us."
    },
    "range": {
      "type": "string",
      "enum": [
        "30d",
        "90d",
        "6m",
        "1y",
        "all"
      ],
      "description": "History range ending on date. 30d and 90d return daily points; 6m, 1y and all return Monday-Sunday UTC weekly buckets clipped to the range."
    },
    "date": {
      "description": "The last day of the range (YYYY-MM-DD). Defaults to the latest chart date.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    }
  },
  "required": [
    "identityType"
  ],
  "additionalProperties": false,
  "description": "Get one podcast's rank history on one chart"
}
```

**Response schema:**
```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "OK"
      ]
    },
    "data": {
      "type": "object",
      "properties": {
        "history": {
          "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."
            },
            "chart": {
              "type": "object",
              "properties": {
                "chartType": {
                  "type": "string",
                  "enum": [
                    "apple",
                    "spotify"
                  ],
                  "description": "The type of chart, one of apple, spotify"
                },
                "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\""
                },
                "country": {
                  "type": "string",
                  "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us."
                },
                "earliestChartDate": {
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                  "description": "The date of the chart in YYYY-MM-DD format"
                },
                "latestChartDate": {
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                  "description": "The date of the chart in YYYY-MM-DD format"
                }
              },
              "required": [
                "chartType",
                "category",
                "country",
                "earliestChartDate",
                "latestChartDate"
              ],
              "additionalProperties": false
            },
            "range": {
              "type": "object",
              "properties": {
                "range": {
                  "type": "string",
                  "enum": [
                    "30d",
                    "90d",
                    "6m",
                    "1y",
                    "all"
                  ],
                  "description": "History range ending on date. 30d and 90d return daily points; 6m, 1y and all return Monday-Sunday UTC weekly buckets clipped to the range."
                },
                "startDate": {
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                  "description": "The date of the chart in YYYY-MM-DD format"
                },
                "endDate": {
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                  "description": "The date of the chart in YYYY-MM-DD format"
                }
              },
              "required": [
                "range",
                "startDate",
                "endDate"
              ],
              "additionalProperties": false
            },
            "stats": {
              "type": "object",
              "properties": {
                "bestPosition": {
                  "nullable": true,
                  "type": "number"
                },
                "averagePositionWhenCharting": {
                  "nullable": true,
                  "description": "Average rank when charting: the mean of every observed daily rank in the range.",
                  "type": "number"
                },
                "daysOnChart": {
                  "type": "number"
                },
                "chartDays": {
                  "type": "number",
                  "description": "Days in the range with a captured chart."
                },
                "offChartDays": {
                  "type": "number"
                },
                "unknownDays": {
                  "type": "number"
                },
                "missingDays": {
                  "type": "number",
                  "description": "Days in the range with no captured chart."
                },
                "calendarDays": {
                  "type": "number"
                },
                "firstSeenDate": {
                  "nullable": true,
                  "description": "Earliest observed appearance on this chart up to the end date, possibly before the range.",
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                },
                "lastSeenDate": {
                  "nullable": true,
                  "description": "Latest observed appearance on this chart up to the end date.",
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                },
                "streak": {
                  "type": "object",
                  "properties": {
                    "days": {
                      "nullable": true,
                      "description": "Consecutive observed days ending on the end date: 0 when confirmed off chart, null when unknown.",
                      "type": "number"
                    },
                    "endDateStatus": {
                      "type": "string",
                      "enum": [
                        "observed",
                        "off_chart",
                        "no_chart",
                        "unknown"
                      ],
                      "description": "observed: ranked that day. off_chart: a fully resolved chart exists and the show is not on it. no_chart: no chart was captured that day. unknown: a chart exists but its coverage cannot prove absence."
                    },
                    "startDate": {
                      "nullable": true,
                      "type": "string",
                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                      "description": "The date of the chart in YYYY-MM-DD format"
                    },
                    "boundedByMissingCoverage": {
                      "type": "boolean",
                      "description": "True when the day before the streak has no chart or unknown coverage, so it may be longer."
                    }
                  },
                  "required": [
                    "days",
                    "endDateStatus",
                    "startDate",
                    "boundedByMissingCoverage"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "bestPosition",
                "averagePositionWhenCharting",
                "daysOnChart",
                "chartDays",
                "offChartDays",
                "unknownDays",
                "missingDays",
                "calendarDays",
                "firstSeenDate",
                "lastSeenDate",
                "streak"
              ],
              "additionalProperties": false
            },
            "series": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "resolution": {
                      "type": "string",
                      "enum": [
                        "daily"
                      ]
                    },
                    "points": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "date": {
                            "type": "string",
                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                            "description": "The date of the chart in YYYY-MM-DD format"
                          },
                          "position": {
                            "nullable": true,
                            "description": "Rank that day; null unless status is observed.",
                            "type": "number"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "observed",
                              "off_chart",
                              "no_chart",
                              "unknown"
                            ],
                            "description": "observed: ranked that day. off_chart: a fully resolved chart exists and the show is not on it. no_chart: no chart was captured that day. unknown: a chart exists but its coverage cannot prove absence."
                          },
                          "chartCoverage": {
                            "type": "string",
                            "enum": [
                              "complete",
                              "unresolved_identities",
                              "incomplete",
                              "no_chart"
                            ],
                            "description": "How completely that day’s chart was captured."
                          }
                        },
                        "required": [
                          "date",
                          "position",
                          "status",
                          "chartCoverage"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "resolution",
                    "points"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "resolution": {
                      "type": "string",
                      "enum": [
                        "weekly"
                      ]
                    },
                    "buckets": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "startDate": {
                            "type": "string",
                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                            "description": "First day of the bucket, clipped to the range."
                          },
                          "endDate": {
                            "type": "string",
                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                            "description": "Last day of the bucket, clipped to the range."
                          },
                          "isPartial": {
                            "type": "boolean",
                            "description": "True when the range clips the Monday-Sunday week."
                          },
                          "calendarDays": {
                            "type": "number"
                          },
                          "bestPosition": {
                            "nullable": true,
                            "type": "number"
                          },
                          "averagePosition": {
                            "nullable": true,
                            "description": "Average of the observed daily ranks in the bucket.",
                            "type": "number"
                          },
                          "daysCharted": {
                            "type": "number"
                          },
                          "chartDays": {
                            "type": "number",
                            "description": "Days in the bucket with a captured chart."
                          },
                          "offChartDays": {
                            "type": "number"
                          },
                          "unknownDays": {
                            "type": "number",
                            "description": "Captured charts whose coverage cannot prove the show was absent."
                          },
                          "missingDates": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                              "description": "The date of the chart in YYYY-MM-DD format"
                            },
                            "description": "Days in the bucket with no captured chart."
                          },
                          "hasCoverageGaps": {
                            "type": "boolean",
                            "description": "True when any day is missing or unknown; break connecting lines through this bucket."
                          }
                        },
                        "required": [
                          "startDate",
                          "endDate",
                          "isPartial",
                          "calendarDays",
                          "bestPosition",
                          "averagePosition",
                          "daysCharted",
                          "chartDays",
                          "offChartDays",
                          "unknownDays",
                          "missingDates",
                          "hasCoverageGaps"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "resolution",
                    "buckets"
                  ],
                  "additionalProperties": false
                }
              ]
            }
          },
          "required": [
            "podenginePodcast",
            "podcastOnChart",
            "identity",
            "chart",
            "range",
            "stats",
            "series"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "history"
      ],
      "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