Historical Chart

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

Get a historical chart

Example request

curl -X GET "https://api.podengine.ai/api/v1/charts?category=top+podcasts&chartType=apple&country=us&date=2026-09-22" \
  -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?category=top+podcasts&chartType=apple&country=us&date=2026-09-22", 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?category=top+podcasts&chartType=apple&country=us&date=2026-09-22", 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?category=top+podcasts&chartType=apple&country=us&date=2026-09-22");
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?category=top+podcasts&chartType=apple&country=us&date=2026-09-22", 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.getChart({
  chartType: 'apple',
  category: 'top podcasts',
  country: 'us',
  date: '2026-09-22',
});

console.log(data);

import os

from podengine import PodEngine

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

data = pe.charts.get_chart(
    chart_type="apple",
    category="top podcasts",
    country="us",
    date="2026-09-22",
)

print(data)

200

Example response

{
  "status": "OK",
  "data": {
    "options": {
      "chartType": "apple",
      "category": "string",
      "country": "string",
      "positionsLimit": 1,
      "compare": "1d",
      "date": "string"
    },
    "chart": {
      "chart": {
        "chartType": "apple",
        "category": "string",
        "country": "string",
        "chartDate": "string",
        "totalPositions": 0,
        "unresolvedPositions": 0,
        "observedDepth": 0,
        "coverageStatus": "complete",
        "compare": "1d",
        "requestedCompareDate": "string",
        "compareChartDate": "string",
        "comparisonStatus": "available",
        "comparisonUnavailableReason": "no_earlier_chart",
        "compareChartObservedDepth": 0,
        "compareChartCoverageStatus": "complete",
        "entryExitConfirmable": true,
        "historyWindow": {
          "dates": [
            "string"
          ],
          "coverage": [
            "complete"
          ]
        }
      },
      "positions": [
        {
          "position": 0,
          "estimatedMonthlyListeners": 0,
          "podcastOnChart": {
            "podcastOnChartId": "string",
            "title": "string",
            "creator": "string",
            "imageUrl": "https://example.com"
          },
          "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"
          },
          "previousPosition": 0,
          "positionChange": 0,
          "isNew": true,
          "movement": "up",
          "history30d": [
            0
          ],
          "history30dStatus": [
            "observed"
          ],
          "peakPosition30d": 0,
          "daysCharted30d": 0,
          "chartsInWindow30d": 0,
          "unknownDays30d": 0
        }
      ]
    }
  }
}

Request

Query parameters

Get a specific podcast chart

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.

positionsLimitnumber1 – 200

The number of chart positions to return. If not provided, all positions are returned

compareenum

Which earlier chart to measure rank change against: 1 day or 7 days before the chart date. The latest chart on or before that date is used. Defaults to 1d.

1d7d

datestringnullableregex

The date of the chart in YYYY-MM-DD format. If null will return the latest chart

Response

200 application/json

statusliteral: OKrequired

dataobjectrequired2 fields

optionsobjectrequired6 fields

Get a specific podcast chart

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.

positionsLimitnumber1 – 200

The number of chart positions to return. If not provided, all positions are returned

compareenum

Which earlier chart to measure rank change against: 1 day or 7 days before the chart date. The latest chart on or before that date is used. Defaults to 1d.

1d7d

datestringnullableregex

The date of the chart in YYYY-MM-DD format. If null will return the latest chart

chartobjectrequirednullable2 fields

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

chartDatestringrequiredregex

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

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

compareenumrequired

Which earlier chart to measure rank change against: 1 day or 7 days before the chart date. The latest chart on or before that date is used. Defaults to 1d.

1d7d

requestedCompareDatestringrequiredregex

The chart date minus 1 or 7 UTC calendar days.

compareChartDatestringrequirednullableregex

The date of the chart actually compared against: the latest chart on or before requestedCompareDate.

comparisonStatusenumrequired

availableunavailable

comparisonUnavailableReasonenumrequirednullable

Why no comparison chart could be resolved; null when comparisonStatus is available.

no_earlier_chart

compareChartObservedDepthnumberrequirednullable

compareChartCoverageStatusenumrequirednullable

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

entryExitConfirmablebooleanrequired

Whether entries can be confirmed: both charts are fully resolved and captured to the same depth. When false, shows absent from the comparison chart have movement unknown.

historyWindowobjectrequired2 fields

The dates that each position's history30d values line up with.

datesarray of stringrequired

The 30 calendar dates ending on chartDate, oldest first.

coveragearray of enumrequired

Chart capture status for each date in dates; no_chart marks a gap that must not be interpolated.

completeunresolved_identitiesincompleteno_chart

positionsarray of objectrequired14 fields

positionnumberrequired

estimatedMonthlyListenersnumberrequirednullablemin 0

Latest published monthly audience estimate for the podcast, independent of the chart date and country.

podcastOnChartobjectrequired4 fields

podcastOnChartIdstringrequired

titlestringrequired

creatorstringrequirednullable

imageUrlstringrequirednullableurl

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

previousPositionnumberrequirednullable

Rank on the comparison chart. Null when absent or unknown; see movement to tell these apart.

positionChangenumberrequirednullable

previousPosition minus position; positive means the show climbed. Null when previousPosition is null.

isNewbooleanrequirednullable

True for a confirmed entry since the comparison chart, false when on both charts, null when unknown.

movementenumrequired

Rank movement against the comparison chart. entered means on this chart but confirmed absent from the comparison chart (re-entries included, not a debut). unknown means no comparison chart or not enough coverage to decide.

updownunchangedenteredunknown

history30darray of numberrequired

Rank on each chart.historyWindow date, oldest first; null when not observed that day.

history30dStatusarray of enumrequired

Status of each history30d value.

observedoff_chartno_chartunknown

peakPosition30dnumberrequirednullable

Best observed rank in the window.

daysCharted30dnumberrequired

Days in the window the show was observed on the chart.

chartsInWindow30dnumberrequired

Charts captured in the window (not calendar days).

unknownDays30dnumberrequired

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