API recipe

Apple Reviews for Top Podcasts Chart

Fetch an Apple Podcasts chart and read ratings and written reviews for its podcasts.

beginner 10 minutes PodEngine Team
ChartsPodcastsReviews

Before you start

  • API token for the reviews endpoint

Choose your example

Your selection applies to every step. HTTP uses built-in clients without the Pod Engine libraries.

Use Node.js 22 or newer. Save the complete script as recipe.mjs.

npm install @podengine/sdk
# macOS / Linux shell; set the same variable in your shell on Windows
export PODENGINE_API_KEY="YOUR_API_KEY"
node recipe.mjs

Set up the client

Start your file with this setup, then append each step in order. The complete script below includes everything.

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

const apiKey = process.env.PODENGINE_API_KEY;
if (!apiKey) throw new Error('Set PODENGINE_API_KEY before running this recipe');
const pe = new PodEngine({
  apiKey,
  baseUrl: process.env.PODENGINE_API_URL || 'https://api.podengine.ai',
});
Complete runnable script
Download script
import { PodEngine } from '@podengine/sdk';

const apiKey = process.env.PODENGINE_API_KEY;
if (!apiKey) throw new Error('Set PODENGINE_API_KEY before running this recipe');
const pe = new PodEngine({
  apiKey,
  baseUrl: process.env.PODENGINE_API_URL || 'https://api.podengine.ai',
});

const { chart } = await pe.charts.getLatestChart({
  chartType: 'apple',
  country: 'us',
  category: 'top podcasts',
  positionsLimit: 5,
});
if (!chart) throw new Error('No chart available for these options');
console.log(`Found ${chart.positions.length} chart positions`);

for (const position of chart.positions) {
  const podcast = position.podenginePodcast;
  if (!podcast) continue; // Some chart entries have not been matched to Pod Engine.
  const { podcastReviews } = await pe.podcasts.getPodcastReviews({
    podcastIdOrSlug: podcast.id,
    country: 'gb',
    limit: 100,
  });
  console.log(podcast.title);
  for (const aggregate of podcastReviews.applePodcastsReviewsByCountry) {
    console.log(`${aggregate.country}: ${aggregate.rating} (${aggregate.reviewsCount} ratings)`);
  }
  if (!podcastReviews.applePodcastsReviewText) {
    console.info('No written review data available');
    continue;
  }
  const { total, reviews } = podcastReviews.applePodcastsReviewText;
  console.log(`${total} reviews total; showing ${reviews.length}`);
  console.dir(reviews, { depth: null });
}
1

Get the Top Podcasts Chart

Request the first five positions in the US Apple top podcasts chart. Each position contains chart information and a podenginePodcast when the entry has been matched to our database. Handle a missing chart before reading its positions.

const { chart } = await pe.charts.getLatestChart({
  chartType: 'apple',
  country: 'us',
  category: 'top podcasts',
  positionsLimit: 5,
});
if (!chart) throw new Error('No chart available for these options');
console.log(`Found ${chart.positions.length} chart positions`);
2

Get the Reviews

Skip chart positions without a matched Pod Engine podcast, then fetch reviews for each remaining podcast. This example scopes reviews to the GB storefront and prints aggregate ratings plus up to 100 written reviews. Python SDK examples convert typed response models to dictionaries with API field names using model_dump(by_alias=True, mode="json").

for (const position of chart.positions) {
  const podcast = position.podenginePodcast;
  if (!podcast) continue; // Some chart entries have not been matched to Pod Engine.
  const { podcastReviews } = await pe.podcasts.getPodcastReviews({
    podcastIdOrSlug: podcast.id,
    country: 'gb',
    limit: 100,
  });
  console.log(podcast.title);
  for (const aggregate of podcastReviews.applePodcastsReviewsByCountry) {
    console.log(`${aggregate.country}: ${aggregate.rating} (${aggregate.reviewsCount} ratings)`);
  }
  if (!podcastReviews.applePodcastsReviewText) {
    console.info('No written review data available');
    continue;
  }
  const { total, reviews } = podcastReviews.applePodcastsReviewText;
  console.log(`${total} reviews total; showing ${reviews.length}`);
  console.dir(reviews, { depth: null });
}