Chart Rank History

GET https://api.podengine.ai/api/v1/charts/history

Get the daily ranks of a chart's top shows on the end date over the preceding 7 to 90 days, with each day's chart coverage

API token required Markdown for LLMs

OpenAPI spec

Example request

Install & configure

curl -X GET "https://api.podengine.ai/api/v1/charts/history?category=top+podcasts&chartType=apple&country=us&days=30&rows=12" \
  -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/history?category=top+podcasts&chartType=apple&country=us&days=30&rows=12", 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/history?category=top+podcasts&chartType=apple&country=us&days=30&rows=12", 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/history?category=top+podcasts&chartType=apple&country=us&days=30&rows=12");
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/history?category=top+podcasts&chartType=apple&country=us&days=30&rows=12", 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.getChartRankHistory({
  chartType: 'apple',
  category: 'top podcasts',
  country: 'us',
  days: 30,
  rows: 12,
});

console.log(data);

import os

from podengine import PodEngine

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

data = pe.charts.get_chart_rank_history(
    chart_type="apple",
    category="top podcasts",
    country="us",
    days=30,
    rows=12,
)

print(data)

200

Example response

{
  "status": "OK",
  "data": {
    "options": {
      "chartType": "apple",
      "category": "string",
      "country": "string",
      "endDate": "string",
      "days": 7,
      "rows": 1
    },
    "history": {
      "chart": {
        "chartType": "apple",
        "category": "string",
        "country": "string",
        "startDate": "string",
        "endDate": "string",
        "days": 0,
        "endDateStatus": "available",
        "endChart": {
          "totalPositions": 0,
          "unresolvedPositions": 0,
          "observedDepth": 0,
          "coverageStatus": "complete"
        },
        "requestedRows": 0,
        "actualRows": 0,
        "coverage": {
          "calendarDays": 0,
          "chartDays": 0,
          "missingDays": 0,
          "completeDays": 0,
          "unresolvedIdentityDays": 0,
          "incompleteDays": 0,
          "minObservedDepth": 0,
          "maxObservedDepth": 0,
          "depthChanged": true
        }
      },
      "dates": [
        {
          "date": "string",
          "coverage": "complete",
          "observedDepth": 0,
          "totalPositions": 0,
          "unresolvedPositions": 0
        }
      ],
      "rows": [
        {
          "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"
          },
          "position": 0,
          "identity": {
            "type": "podcast",
            "podcastId": "string",
            "slug": "string"
          },
          "platformId": "string",
          "title": "string",
          "creator": "string",
          "imageUrl": "string",
          "ranks": [
            {
              "position": 0,
              "status": "observed"
            }
          ],
          "bestPosition": 0,
          "daysCharted": 0,
          "unknownDays": 0
        }
      ]
    }
  }
}

Request

Query parameters

Get the daily ranks of the top shows on a chart over a window of days

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.

endDatestringregex

The last day of the window (YYYY-MM-DD). Exact: when no chart was captured that day the response has no rows. Defaults to the latest chart date.

daysnumber7 – 90

Calendar days in the window, ending on endDate. 7-90, default 30.

rowsnumber1 – 50

How many of the end date's top shows to return, default 12, max 50.

Response

200 application/json

statusliteral: OKrequired

dataobjectrequired2 fields

optionsobjectrequired6 fields

Get the daily ranks of the top shows on a chart over a window of days

chartTypeenum

The type of chart, one of apple, spotify

applespotify

categorystring

countrystring

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

endDatestringregex

The last day of the window (YYYY-MM-DD). Exact: when no chart was captured that day the response has no rows. Defaults to the latest chart date.

daysnumber7 – 90

Calendar days in the window, ending on endDate. 7-90, default 30.

rowsnumber1 – 50

How many of the end date's top shows to return, default 12, max 50.

historyobjectrequirednullable3 fields

Null when this chart has never been captured.

chartobjectrequired11 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.

startDatestringrequiredregex

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

endDatestringrequiredregex

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

daysnumberrequired

endDateStatusenumrequired

no_chart: nothing was captured on endDate, so there is no cohort and rows is empty.

availableno_chart

endChartobjectrequirednullable4 fields

The full end-date chart, independent of rows; null when endDateStatus is no_chart.

totalPositionsnumberrequired

Positions with a platform identity on this chart, independent of positionsLimit.

unresolvedPositionsnumberrequired

Historical Spotify positions recorded without a trustworthy Spotify id (not included in positions).

observedDepthnumberrequired

The deepest position captured for this chart.

coverageStatusenumrequired

complete: every captured position has a platform id. unresolved_identities: some historical Spotify positions are known only by Pod Engine podcast. incomplete: positions are missing from the capture.

completeunresolved_identitiesincomplete

requestedRowsnumberrequired

actualRowsnumberrequired

Rows returned; fewer than requestedRows when the end-date chart is shorter.

coverageobjectrequired9 fields

calendarDaysnumberrequired

chartDaysnumberrequired

Days with a captured chart.

missingDaysnumberrequired

Days with no captured chart.

completeDaysnumberrequired

unresolvedIdentityDaysnumberrequired

Days whose chart has Spotify positions known only by podcast.

incompleteDaysnumberrequired

Days whose chart is missing positions.

minObservedDepthnumberrequirednullable

maxObservedDepthnumberrequirednullable

depthChangedbooleanrequired

True when charts in the window were captured to different depths, so off chart means different cut-offs.

datesarray of objectrequired5 fields

Every UTC calendar day from startDate to endDate, oldest first.

datestringrequiredregex

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

coverageenumrequired

no_chart marks a day with no captured chart: never interpolate it.

completeunresolved_identitiesincompleteno_chart

observedDepthnumberrequirednullable

The deepest position captured that day; null when no chart.

totalPositionsnumberrequirednullable

Positions with a platform identity that day; null when no chart.

unresolvedPositionsnumberrequirednullable

Historical Spotify positions known only by Pod Engine podcast that day; null when no chart.

rowsarray of objectrequired11 fields

The end date's top shows by rank. Shows that charted earlier in the window but are not in this cohort are left out.

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

positionnumberrequired

Rank on the end date; rows are in this order.

identityunionrequired

platform for a listed show; podcast for a historical Spotify position known only by its Pod Engine podcast, whose ranks then cover every Spotify id matched to it.

platformIdstringrequirednullable

The Apple or Spotify id; null when no trustworthy platform id exists.

titlestringrequired

creatorstringrequirednullable

imageUrlstringrequirednullable

ranksarray of objectrequired2 fields

One entry per dates entry, oldest first.

positionnumberrequirednullable

Rank that day; null unless status is observed.

statusenumrequired

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

bestPositionnumberrequirednullable

Best observed rank in the window.

daysChartednumberrequired

Days in the window the show was observed.

unknownDaysnumberrequired

Captured charts in the window whose coverage cannot prove the show was absent.