Podcast Chart History

GET https://api.podengine.ai/api/v1/charts/podcast-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

API token required Markdown for LLMs

OpenAPI spec

Example request

Install & configure

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: YOUR_API_TOKEN"

const options = {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_TOKEN"
  }
};

fetch("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", options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_TOKEN"
}

response = requests.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", headers=headers)
print(response.json())

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "YOUR_API_TOKEN");
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var response = await client.GetAsync("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");
var data = await response.Content.ReadAsStringAsync();
Console.WriteLine(data);

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("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", nil)
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "YOUR_API_TOKEN")
	
	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

import { PodEngine } from '@podengine/sdk';

const pe = new PodEngine({ apiKey: process.env.PODENGINE_API_KEY });

const data = await pe.charts.getPodcastChartHistory({
  identityType: 'podcast',
  podcastIdOrSlug: 'good-hang-with-amy-poehler',
  chartType: 'apple',
  category: 'top podcasts',
  country: 'us',
  range: '30d',
});

console.log(data);

import os

from podengine import PodEngine

pe = PodEngine(api_key=os.environ["PODENGINE_API_KEY"])

data = pe.charts.get_podcast_chart_history(
    identity_type="podcast",
    podcast_id_or_slug="good-hang-with-amy-poehler",
    chart_type="apple",
    category="top podcasts",
    country="us",
    range="30d",
)

print(data)

200

Example response

{
  "status": "OK",
  "data": {
    "history": {
      "podenginePodcast": {
        "author": "string",
        "authorityScore": {
          "calculatedAt": "2026-01-15T09:30:00.000Z",
          "authorityScore": 0,
          "qualityScore": 0,
          "youtubeScore": 0,
          "socialScore": 0,
          "engagementScore": 0
        },
        "genres": [
          "string"
        ],
        "id": "string",
        "imageUrl": "string",
        "language": "string",
        "lastEpisodePublishedAt": "2026-01-15T09:30:00.000Z",
        "slug": "string",
        "title": "string",
        "titleLatest": "string"
      },
      "podcastOnChart": {
        "platformId": "string",
        "title": "string",
        "creator": "string",
        "imageUrl": "string"
      },
      "identity": {
        "type": "podcast",
        "podcastId": "string",
        "slug": "string"
      },
      "chart": {
        "chartType": "apple",
        "category": "string",
        "country": "string",
        "earliestChartDate": "string",
        "latestChartDate": "string"
      },
      "range": {
        "range": "30d",
        "startDate": "string",
        "endDate": "string"
      },
      "stats": {
        "bestPosition": 0,
        "averagePositionWhenCharting": 0,
        "daysOnChart": 0,
        "chartDays": 0,
        "offChartDays": 0,
        "unknownDays": 0,
        "missingDays": 0,
        "calendarDays": 0,
        "firstSeenDate": "string",
        "lastSeenDate": "string",
        "streak": {
          "days": 0,
          "endDateStatus": "observed",
          "startDate": "string",
          "boundedByMissingCoverage": true
        }
      },
      "series": {
        "resolution": "daily",
        "points": [
          {
            "date": "string",
            "position": 0,
            "status": "observed",
            "chartCoverage": "complete"
          }
        ]
      }
    }
  }
}

Request

Query parameters

Get one podcast's rank history on one chart

identityTypeenumrequired

podcast: a Pod Engine podcast, given by podcastIdOrSlug. platform: one Apple or Spotify id on the chart type, given by platformId.

podcastplatform

podcastIdOrSlugstringmin 1 characters

Pod Engine podcast id or slug. Required for identityType=podcast.

platformIdstring1 – 64 characters

Apple id or Spotify show id for chartType. Required for identityType=platform.

chartTypeenum

The type of chart, one of apple, spotify

applespotify

categorystring

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"

countrystring

The country of the chart in ISO 3166-1 alpha-2 format, for example "us". Defaults to us.

rangeenum

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.

30d90d6m1yall

datestringregex

The last day of the range (YYYY-MM-DD). Defaults to the latest chart date.

Response

200 application/json

statusliteral: OKrequired

dataobjectrequired1 field

historyobjectrequired7 fields

podenginePodcastobjectrequirednullable10 fields

authorstringrequirednullable

authorityScoreobjectrequirednullable6 fields

calculatedAtdaterequired

authorityScorenumberrequired

This is the weighted total authority score of the podcast, out of 100

qualityScorenumberrequired

This is the quality score of the podcast, out of 100

youtubeScorenumberrequired

This is the YouTube score of the podcast, out of 100

socialScorenumberrequired

This is the social score of the podcast, out of 100

engagementScorenumberrequired

This is the engagement score of the podcast, out of 100

genresarray of stringrequired

idstringrequired

imageUrlstringrequirednullable

languagestringrequired

lastEpisodePublishedAtdaterequired

slugstringrequired

titlestringrequired

titleLateststringrequired

podcastOnChartobjectrequirednullable4 fields

The platform listing, for identityType=platform.

platformIdstringrequired

titlestringrequired

creatorstringrequirednullable

imageUrlstringrequirednullable

identityunionrequired

The resolved identity, stable for deep links: the canonical Pod Engine id, or the platform id.

chartobjectrequired5 fields

chartTypeenumrequired

The type of chart, one of apple, spotify

applespotify

categorystringrequired

countrystringrequired

The country of the chart in ISO 3166-1 alpha-2 format, for example "us". Defaults to us.

earliestChartDatestringrequiredregex

The date of the chart in YYYY-MM-DD format

latestChartDatestringrequiredregex

The date of the chart in YYYY-MM-DD format

rangeobjectrequired3 fields

rangeenumrequired

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.

30d90d6m1yall

startDatestringrequiredregex

The date of the chart in YYYY-MM-DD format

endDatestringrequiredregex

The date of the chart in YYYY-MM-DD format

statsobjectrequired11 fields

bestPositionnumberrequirednullable

averagePositionWhenChartingnumberrequirednullable

Average rank when charting: the mean of every observed daily rank in the range.

daysOnChartnumberrequired

chartDaysnumberrequired

Days in the range with a captured chart.

offChartDaysnumberrequired

unknownDaysnumberrequired

missingDaysnumberrequired

Days in the range with no captured chart.

calendarDaysnumberrequired

firstSeenDatestringrequirednullableregex

Earliest observed appearance on this chart up to the end date, possibly before the range.

lastSeenDatestringrequirednullableregex

Latest observed appearance on this chart up to the end date.

streakobjectrequired4 fields

daysnumberrequirednullable

Consecutive observed days ending on the end date: 0 when confirmed off chart, null when unknown.

endDateStatusenumrequired

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.

observedoff_chartno_chartunknown

startDatestringrequirednullableregex

The date of the chart in YYYY-MM-DD format

boundedByMissingCoveragebooleanrequired

True when the day before the streak has no chart or unknown coverage, so it may be longer.

seriesunionrequired