Chart Movement

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

Get a chart's biggest climbers and fallers, new entries and drop-offs since the chart 1 or 7 days earlier, computed over every position

API token required Markdown for LLMs

OpenAPI spec

Example request

Install & configure

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

console.log(data);

import os

from podengine import PodEngine

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

data = pe.charts.get_chart_movement(
    chart_type="apple",
    category="top podcasts",
    country="us",
    compare="1d",
)

print(data)

200

Example response

{
  "status": "OK",
  "data": {
    "options": {
      "chartType": "apple",
      "category": "string",
      "country": "string",
      "date": "string",
      "compare": "1d",
      "limit": 1
    },
    "movement": {
      "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
      },
      "climbers": {
        "status": "available",
        "unavailableReason": "no_earlier_chart",
        "totalCount": 0,
        "items": [
          {
            "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"
            },
            "identity": {
              "type": "podcast",
              "podcastId": "string",
              "slug": "string"
            },
            "title": "string",
            "creator": "string",
            "imageUrl": "string",
            "position": 0,
            "previousPosition": 0,
            "positionChange": 0
          }
        ]
      },
      "fallers": {
        "status": "available",
        "unavailableReason": "no_earlier_chart",
        "totalCount": 0,
        "items": [
          {
            "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"
            },
            "identity": {
              "type": "podcast",
              "podcastId": "string",
              "slug": "string"
            },
            "title": "string",
            "creator": "string",
            "imageUrl": "string",
            "position": 0,
            "previousPosition": 0,
            "positionChange": 0
          }
        ]
      },
      "newEntries": {
        "status": "available",
        "unavailableReason": "no_earlier_chart",
        "totalCount": 0,
        "items": [
          {
            "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"
            },
            "identity": {
              "type": "podcast",
              "podcastId": "string",
              "slug": "string"
            },
            "title": "string",
            "creator": "string",
            "imageUrl": "string",
            "position": 0,
            "previousPosition": 0,
            "positionChange": 0
          }
        ]
      },
      "droppedOff": {
        "status": "available",
        "unavailableReason": "no_earlier_chart",
        "totalCount": 0,
        "items": [
          {
            "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"
            },
            "identity": {
              "type": "podcast",
              "podcastId": "string",
              "slug": "string"
            },
            "title": "string",
            "creator": "string",
            "imageUrl": "string",
            "position": 0,
            "previousPosition": 0,
            "positionChange": 0
          }
        ]
      }
    }
  }
}

Request

Query parameters

Get a chart's biggest climbers and fallers, new entries and drop-offs since a comparison 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.

datestringnullableregex

The chart date (YYYY-MM-DD). Omit for the latest chart; pass the date on screen to stay on one snapshot.

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

limitnumber1 – 25

Items per list, default 4, max 25. Lists are computed over the whole chart; totalCount is unaffected.

Response

200 application/json

statusliteral: OKrequired

dataobjectrequired2 fields

optionsobjectrequired6 fields

Get a chart's biggest climbers and fallers, new entries and drop-offs since a comparison 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.

datestringnullableregex

The chart date (YYYY-MM-DD). Omit for the latest chart; pass the date on screen to stay on one snapshot.

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

limitnumber1 – 25

Items per list, default 4, max 25. Lists are computed over the whole chart; totalCount is unaffected.

movementobjectrequirednullable5 fields

Null when no chart exists for the date.

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

climbersobjectrequired4 fields

Largest climbs among shows on both charts, biggest first.

statusenumrequired

unavailable: the list cannot be computed reliably, which is different from an empty list.

availableunavailable

unavailableReasonenumrequirednullable

no_earlier_chart: nothing to compare with. depth_changed: the charts were captured to different depths. incomplete_coverage: a chart has missing or unresolved positions.

no_earlier_chartdepth_changedincomplete_coverage

totalCountnumberrequired

Items in the full list, independent of limit.

itemsarray of objectrequired8 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

identityunionrequired

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

titlestringrequired

creatorstringrequirednullable

imageUrlstringrequirednullable

positionnumberrequirednullable

Rank on the chart; null for a dropped show.

previousPositionnumberrequirednullable

Rank on the comparison chart; null for an entry.

positionChangenumberrequirednullable

previousPosition minus position; positive means the show climbed. Null unless on both charts.

fallersobjectrequired4 fields

Largest falls among shows on both charts, biggest first.

statusenumrequired

unavailable: the list cannot be computed reliably, which is different from an empty list.

availableunavailable

unavailableReasonenumrequirednullable

no_earlier_chart: nothing to compare with. depth_changed: the charts were captured to different depths. incomplete_coverage: a chart has missing or unresolved positions.

no_earlier_chartdepth_changedincomplete_coverage

totalCountnumberrequired

Items in the full list, independent of limit.

itemsarray of objectrequired8 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

identityunionrequired

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

titlestringrequired

creatorstringrequirednullable

imageUrlstringrequirednullable

positionnumberrequirednullable

Rank on the chart; null for a dropped show.

previousPositionnumberrequirednullable

Rank on the comparison chart; null for an entry.

positionChangenumberrequirednullable

previousPosition minus position; positive means the show climbed. Null unless on both charts.

newEntriesobjectrequired4 fields

Confirmed entries since the comparison chart, by position. May include re-entries; not a debut.

statusenumrequired

unavailable: the list cannot be computed reliably, which is different from an empty list.

availableunavailable

unavailableReasonenumrequirednullable

no_earlier_chart: nothing to compare with. depth_changed: the charts were captured to different depths. incomplete_coverage: a chart has missing or unresolved positions.

no_earlier_chartdepth_changedincomplete_coverage

totalCountnumberrequired

Items in the full list, independent of limit.

itemsarray of objectrequired8 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

identityunionrequired

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

titlestringrequired

creatorstringrequirednullable

imageUrlstringrequirednullable

positionnumberrequirednullable

Rank on the chart; null for a dropped show.

previousPositionnumberrequirednullable

Rank on the comparison chart; null for an entry.

positionChangenumberrequirednullable

previousPosition minus position; positive means the show climbed. Null unless on both charts.

droppedOffobjectrequired4 fields

Shows on the comparison chart confirmed absent from this one, by their last position.

statusenumrequired

unavailable: the list cannot be computed reliably, which is different from an empty list.

availableunavailable

unavailableReasonenumrequirednullable

no_earlier_chart: nothing to compare with. depth_changed: the charts were captured to different depths. incomplete_coverage: a chart has missing or unresolved positions.

no_earlier_chartdepth_changedincomplete_coverage

totalCountnumberrequired

Items in the full list, independent of limit.

itemsarray of objectrequired8 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

identityunionrequired

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

titlestringrequired

creatorstringrequirednullable

imageUrlstringrequirednullable

positionnumberrequirednullable

Rank on the chart; null for a dropped show.

previousPositionnumberrequirednullable

Rank on the comparison chart; null for an entry.

positionChangenumberrequirednullable

previousPosition minus position; positive means the show climbed. Null unless on both charts.