Getting Charts for an Individual Podcast
Note: Getting charts requires our plus or pro plans.
Within our API, you can get charts from Apple Podcasts or Spotify for any podcast that has ranked in those charts. There are a few ways to get the charts so, in this guide, we will look at getting them for an individual podcast that we know either the Apple Podcasts ID (formerly known as the iTunes ID) or the RSS feed URL for.
If you haven't already, you will need to get your authorization token which you can get by following our "Your First Podchaser Query" guide.
Exploring the Podcast Query
In order to get an individual podcast, you can use our podcast query. An example query for this would look like this:
POST https://api.podchaser.com/graphql
query {
podcast(identifier: {id: "1073226719", type: APPLE_PODCASTS}) {
title,
description
}
}
The podcast query accepts an identifier which can be:
- Apple Podcasts ID
- Spotify ID
- RSS feed URL
- Podchaser ID
You can see review the documention for how to structure the identifier and the accepted type values.
We have a variety of fields that can be returned by this query so we encourage you to view the podcast object documentation.
Retrieving Charts
Within the podcast query, you can charts field. This field currently requires a platform and a date. Like our other queries, this returns a paginated list object. You can review the response for the charts field in our ChartPositionPaginator documentation.
This query will return all the positions this podcast ranked for on June 5th, 2021 in Apple Podcasts.
POST https://api.podchaser.com/graphql
query {
podcast(identifier: {id: "1073226719", type: APPLE_PODCASTS}) {
title,
description,
charts(platform: APPLE_PODCASTS, day: "2021-06-05") {
data {
platform,
country,
day,
position,
category
}
}
}
}
This query will have this reponse (though shortened here for brevity):
{
"data": {
"podcast": {
"title": "Pivot",
"description": "Every Tuesday and Friday, Recode’s Kara Swisher and NYU Professor Scott Galloway offer sharp, unfiltered insights into the biggest stories in tech, business, and politics. They make bold predictions, pick winners and losers, and bicker and banter like no one else. After all, with great power comes great scrutiny. From New York Magazine and the Vox Media Podcast Network.",
"charts": {
"data": [
{
"platform": "APPLE_PODCASTS",
"country": "ae",
"day": "2021-06-05",
"position": 21,
"category": "News"
},
...other charts...
]
}
}
}
}
Filtering By Country
The charts field also accepts a country value for returning only charts for a specific country. These will be in 2-character country code format.
This query will return all the positions this podcast ranked for on June 5th, 2021 in Apple Podcasts for the United States.
POST https://api.podchaser.com/graphql
query {
podcast(identifier: {id: "1073226719", type: APPLE_PODCASTS}) {
title,
description,
charts(platform: APPLE_PODCASTS, day: "2021-06-05", country: "us") {
data {
platform,
country,
day,
position,
category
}
}
}
}
This query will have this reponse:
{
"data": {
"podcast": {
"title": "Pivot",
"description": "Every Tuesday and Friday, Recode’s Kara Swisher and NYU Professor Scott Galloway offer sharp, unfiltered insights into the biggest stories in tech, business, and politics. They make bold predictions, pick winners and losers, and bicker and banter like no one else. After all, with great power comes great scrutiny. From New York Magazine and the Vox Media Podcast Network.",
"charts": {
"data": [
{
"platform": "APPLE_PODCASTS",
"country": "us",
"day": "2021-06-05",
"position": 186,
"category": "History"
},
{
"platform": "APPLE_PODCASTS",
"country": "us",
"day": "2021-06-05",
"position": 30,
"category": "News"
},
{
"platform": "APPLE_PODCASTS",
"country": "us",
"day": "2021-06-05",
"position": 8,
"category": "News Commentary"
},
{
"platform": "APPLE_PODCASTS",
"country": "us",
"day": "2021-06-05",
"position": 186,
"category": "All Categories"
}
]
}
}
}
}
Sorting Charts
The chart query also allows you to sort by position or country. You can pass an array to the sort parameter and include the direction for the sort. The value would look like [{column: CATEGORY, order: ASC}] where the column value is POSITION, CATEGORY, or COUNTRY.
This query will return all the positions this podcast ranked for on June 5th, 2021 in Apple Podcasts sorted in ascending position order (i.e. best ranks first).
POST https://api.podchaser.com/graphql
query {
podcast(identifier: {id: "1073226719", type: APPLE_PODCASTS}) {
title,
description,
charts(platform: APPLE_PODCASTS, day: "2021-06-05", sort:[{column:POSITION, order:ASC}]) {
data {
platform,
country,
day,
position,
category
}
}
}
}
This query will have this reponse (though shortened here for brevity):
{
"data": {
"podcast": {
"title": "Pivot",
"description": "Every Tuesday and Friday, Recode’s Kara Swisher and NYU Professor Scott Galloway offer sharp, unfiltered insights into the biggest stories in tech, business, and politics. They make bold predictions, pick winners and losers, and bicker and banter like no one else. After all, with great power comes great scrutiny. From New York Magazine and the Vox Media Podcast Network.",
"charts": {
"data": [
{
"platform": "APPLE_PODCASTS",
"country": "ae",
"day": "2021-06-05",
"position": 1,
"category": "News Commentary"
},
{
"platform": "APPLE_PODCASTS",
"country": "at",
"day": "2021-06-05",
"position": 1,
"category": "News Commentary"
},
...other charts...
]
}
}
}
}
Using Aliasing to get Multiple Charts
Within GraphQL, you can use aliasing to get the same field with different parameters. We can use this to get charts for both Apple and Spotify in one request.
To do this, we use the ALIAS:FIELD syntax. For example, we could use appleCharts: charts(). The alias can be whatever text you choose.
This query will return all the positions this podcast ranked for on June 5th, 2021 in Apple Podcasts and Spotify.
POST https://api.podchaser.com/graphql
query {
podcast(identifier: {id: "1073226719", type: APPLE_PODCASTS}) {
title,
description,
appleCharts:charts(platform: APPLE_PODCASTS, day: "2021-06-05", sort:[{column:POSITION, order:ASC}]) {
data {
platform,
country,
day,
position,
category
}
},
spotifyCharts:charts(platform: SPOTIFY, day: "2021-06-05", sort:[{column:POSITION, order:ASC}]) {
data {
platform,
country,
day,
position,
category
}
},
}
}
This query will have this reponse (though shortened here for brevity):
{
"data": {
"podcast": {
"title": "Pivot",
"description": "Every Tuesday and Friday, Recode’s Kara Swisher and NYU Professor Scott Galloway offer sharp, unfiltered insights into the biggest stories in tech, business, and politics. They make bold predictions, pick winners and losers, and bicker and banter like no one else. After all, with great power comes great scrutiny. From New York Magazine and the Vox Media Podcast Network.",
"appleCharts": {
"data": [
{
"platform": "APPLE_PODCASTS",
"country": "ae",
"day": "2021-06-05",
"position": 1,
"category": "News Commentary"
},
{
"platform": "APPLE_PODCASTS",
"country": "at",
"day": "2021-06-05",
"position": 1,
"category": "News Commentary"
},
...other charts...
]
},
"spotifyCharts": {
"data": [
{
"platform": "SPOTIFY",
"country": "ad",
"day": "2021-06-05",
"position": 15,
"category": "Business & Technology"
},
{
"platform": "SPOTIFY",
"country": "ie",
"day": "2021-06-05",
"position": 19,
"category": "Business & Technology"
},
...other charts...
]
}
}
}
}
Additionally, you could use alias to retrieve multiple days within the same request. Please note that each additional alias will add additional loading time so it is advised to only use a few aliases for charts within a single request.
Next Steps
Since the charts field returns a paginated list, you may want to review the documentation for the ChartPositionPaginator object returned by the charts field as well as the PaginatorInfo used by paginated lists throughout our API.