Podcastindex.org

NDEx REST API

Download the openapi spec in [json](pi_api.json) or [yaml](pi_api.yaml) format. Overview The Podcast Index (Podcast Index LLC) is a software developer focused…

Media & content#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Download the openapi spec in [json](pi_api.json) or [yaml](pi_api.yaml) format.

Overview

The Podcast Index (Podcast Index LLC) is a software developer focused partnership that provides tools and data to
anyone who aspires to create new and exciting Podcast experiences without the heavy lifting of indexing,
aggregation and data management.

Example Code

Users have provided example code for working the API in the following languages:

Don't see your desired language, create an example repo and create a
Pull Request with a link to your example code project!

Libraries

User created libraries for working with the API:

Are we missing a library? Did you create one for a different language? Create a
Pull Request with a link to the new library!

Postman

A collection file for use in the Postman application is available for this API.

  1. Download the contents of the Postman Docs folder.
  2. Import the PodcastIndex.postman_collection.json collection to Postman
  3. Import the PodcastIndexOrgEnvironment.postman_environment.json to Postman
  4. Click "Environments" on the left sidebar
  5. Select the checkbox next to the PodcastIndexOrgEnvironment entry
  6. Set AuthKey and SeceretKey values under the "Current Value" column using your API information
  7. Click "Collections" from the sidebar
  8. Select PodcastIndex
  9. Select and run the endpoint to test

Contributing

The source for this API documentation is available at
https://github.com/Podcastindex-org/docs-api.
Submit an Issue or create a Pull Request.

Authentication Details

Sending an API request is easy. We use an Amazon-style request authorization token to secure each request.

Register for a free API key at https://api.podcastindex.org/

These headers parameters are required for each request: User-Agent, X-Auth-Date, X-Auth-Key, Authorization

See Authentication for description of parameters.

Legal

Legal

Endpoints 52

Search

  • GETSearch Podcasts/search/byterm?q=batman universityThis call returns all of the feeds that match the search terms in the title, author or owner of the feed. Example:…
  • GETSearch Podcasts by Title/search/bytitle?q=batman universityThis call returns all of the feeds where the title of the feed matches the search term (ignores case). Example "everything everywhere daily" will match the…
  • GETSearch Episodes by Person/search/byperson?q=adam curryThis call returns all of the episodes where the specified person is mentioned. It searches the following fields: Person tags Episode title Episode description…
  • GETSearch Music Podcasts/search/music/byterm?q=batman universityThis call returns all of the feeds that match the search terms in the title, author or owner of the <feed></feed> where the medium is music. Example:…

Podcasts

  • GETBy Feed ID/podcasts/byfeedid?id=75075This call returns everything we know about the feed from the PodcastIndex ID Examples: https://api.podcastindex.org/api/1.0/podcasts/byfeedid?id=75075&pretty…
  • GETBy Feed URL/podcasts/byfeedurl?url=https://feeds.theincomparable.com/batmanuniversityThis call returns everything we know about the feed from the feed URL Examples:…
  • GETBy iTunes ID/podcasts/byitunesid?id=1441923632This call returns everything we know about the feed from the iTunes ID Example: https://api.podcastindex.org/api/1.0/podcasts/byitunesid?id=1441923632&pretty
  • GETBy GUID/podcasts/byguid?guid=9b024349-ccf0-5f69-a609-6b82873eab3cThis call returns everything we know about the feed from the feed's GUID. The GUID is a unique, global identifier for the podcast. See the namespace spec for…
  • GETBy Tag/podcasts/bytagThis call returns all feeds that support the specified podcast namespace tag. The only supported tags are: podcast:value using the podcast-value parameter…
  • GETBy Medium/podcasts/bymediumThis call returns all feeds marked with the specified medium tag value. Example: https://api.podcastindex.org/api/1.0/podcasts/bymedium?medium=music&pretty
  • GETTrending/podcasts/trendingThis call returns the podcasts/feeds that in the index that are trending. Example: https://api.podcastindex.org/api/1.0/podcasts/trending?pretty
  • GETDead/podcasts/deadThis call returns all feeds that have been marked dead (dead == 1) Hourly statistics can also be access at…
  • POSTBatch By Feed GUID/podcasts/batch/byguidThis call returns everything we know about the feed from the feed's GUID provided in JSON array in the body of the request. The GUID is a unique, global…

Episodes

  • GETBy Feed ID/episodes/byfeedid?id=75075This call returns all the episodes we know about for this feed from the PodcastIndex ID. Episodes are in reverse chronological order. When using the enclosure…
  • GETBy Feed URL/episodes/byfeedurl?url=https://feeds.theincomparable.com/batmanuniversityThis call returns all the episodes we know about for this feed from the feed URL. Episodes are in reverse chronological order. Examples:…
  • GETBy Podcast GUID/episodes/bypodcastguid?guid=9b024349-ccf0-5f69-a609-6b82873eab3cThis call returns all the episodes we know about for this feed from the Podcast GUID. Episodes are in reverse chronological order. Example:…
  • GETBy iTunes ID/episodes/byitunesid?id=1441923632This call returns all the episodes we know about for this feed from the iTunes ID. Episodes are in reverse chronological order. When using the enclosure…
  • GETBy ID/episodes/byid?id=16795089Get all the metadata for a single episode by passing its id. Example: https://api.podcastindex.org/api/1.0/episodes/byid?id=16795090&pretty
  • GETBy GUID/episodes/byguid?guid=PC2084Get all the metadata for a single episode by passing its guid and the feed id or URL. The feedid, feedurl, or podcastguid is required. Examples: Search using…
  • GETLive/episodes/liveGet all episodes that have been found in the podcast:liveitem from the feeds. Examples: https://api.podcastindex.org/api/1.0/episodes/live?pretty
  • GETRandom/episodes/randomThis call returns a random batch of episodes, in no specific order. Examples:…

Recent

  • GETEpisodes/recent/episodesThis call returns the most recent max number of episodes globally across the whole index, in reverse chronological order. Example:…
  • GETFeeds/recent/feedsThis call returns the most recent max feeds, in reverse chronological order. Examples: https://api.podcastindex.org/api/1.0/recent/feeds?pretty…
  • GETNew Feeds/recent/newfeedsThis call returns every new feed added to the index over the past 24 hours in reverse chronological order. Examples:…
  • GETNew Value Feeds/recent/newvaluefeedsThis call returns feeds that have added a value tag in reverse chronological order. Example: https://api.podcastindex.org/api/1.0/recent/newvaluefeeds?pretty
  • GETRecent Data/recent/dataThis call returns every new feed and episode added to the index over the past 24 hours in reverse chronological order. This is similar to /recent/feeds but…
  • GETSoundbites/recent/soundbitesThis call returns the most recent max soundbites that the index has discovered. A soundbite consists of an enclosure url, a start time and a duration. It is…

Value

  • GETBy Feed ID/value/byfeedid?id=75075This call returns the information for supporting the podcast via one of the "Value for Value" methods from the PodcastIndex ID. Additionally, the value block…
  • GETBy Feed URL/value/byfeedurl?url=https://feeds.theincomparable.com/batmanuniversityThis call returns the information for supporting the podcast via one of the "Value for Value" methods from feed URL. Additionally, the value block data can be…
  • GETBy Feed GUID/value/bypodcastguid?guid=9b024349-ccf0-5f69-a609-6b82873eab3cThis call returns the information for supporting the podcast via one of the "Value for Value" methods from podcast GUID. Note: No API key needed for this…
  • GETBy Episode GUID/value/byepisodeguid?podcastguid=917393e3-1b1e-5cef-ace4-edaa54e1f810&episodeguid=PC20143This call returns the information for supporting the podcast episode via one of the "Value for Value" methods from podcast GUID and the episode GUID. The…
  • POSTBatch By Episode GUID/value/batch/byepisodeguidThis call returns the information for supporting the podcast episode via one of the "Value for Value" methods from a JSON object containing one or more…

Stats

  • GETCurrent/stats/currentReturn the most recent index statistics. Hourly statistics can also be access at https://stats.podcastindex.org/hourly_counts.json For details, see Stats…

Categories

  • GETList/categories/listReturn all the possible categories supported by the index. Example: https://api.podcastindex.org/api/1.0/categories/list?pretty

Hub

  • GETPub Notify/hub/pubnotifyNotify the index that a feed has changed Note: No API key needed for this endpoint. Examples:…

Add

  • GETBy Feed URL/add/byfeedurl?url=https://feeds.theincomparable.com/batmanuniversity&chash=ad651c60eaaf3344595c0dd0bd787993This call adds a podcast to the index using its feed url. If a feed already exists, you will get its existing Feed ID returned. NOTE: this endpoint requires…
  • POSTBy Feed URL/add/byfeedurl?url=https://feeds.theincomparable.com/batmanuniversityThis call adds a podcast to the index using its feed url. If a feed already exists, you will get its existing Feed ID returned. NOTE: this endpoint requires…
  • GETBy iTunes ID/add/byitunesidThis call adds a podcast to the index using its iTunes ID. If a feed already exists, it will be noted in the response. NOTE: this endpoint requires an API Key…
  • POSTBy iTunes ID/add/byitunesidThis call adds a podcast to the index using its iTunes ID. If a feed already exists, it will be noted in the response. NOTE: this endpoint requires an API Key…

Apple Replacement

  • GETSearchhttps://api.podcastindex.org/search?term=batmanReplaces the Apple search API but returns data from the Podcast Index database. Note: No API key needed for this endpoint. Example: Apple:…
  • GETLookuphttps://api.podcastindex.org/lookup?id=1441923632&entity=podcastReplaces the Apple podcast lookup API but returns data from the Podcast Index database. Note: No API key needed for this endpoint. Example: Apple:…

Static Data

  • GETStats Daily Countshttps://stats.podcastindex.org/static/stats/daily_counts.jsonReport a number of statistics about the feeds in Podcast Index's database. Updated daily. A subset of stats can be retrieved using the API endpoint…
  • GETStats Hourly Countshttps://stats.podcastindex.org/static/stats/hourly_counts.jsonReport a number of statistics about the feeds in Podcast Index's database. Updated hourly. A subset of stats can be retrieved using the API endpoint…
  • GETv4v Satshttps://stats.podcastindex.org/static/stats/chart-data.jsonContains the raw data used to populate the graphs at https://stats.podcastindex.org/v4v. This is a look at the total sats flowing through the Value4Value…
  • GETv4v Music Chart JSONhttps://stats.podcastindex.org/static/stats/v4vmusic.jsonContains the ranking of the music tracks played on podcasts that have been boosted the most over the last 7 days. Each entry shows the number of listener…
  • GETv4v Music Chart OPMLhttps://stats.podcastindex.org/static/stats/v4vmusic.opmlContains the ranking of the music tracks played on podcasts that have been boosted the most over the last 7 days. Each entry shows the number of listener…
  • GETv4v Music Chart RSShttps://stats.podcastindex.org/static/stats/v4vmusic.rssContains the ranking of the music tracks played on podcasts that have been boosted the most over the last 7 days. Each entry shows the number of listener…
  • GETCurrenthttps://tracking.podcastindex.org/static/tracking/currentThis call returns every new feed and episode added to the index over the past 24 hours in reverse chronological order. This is similar to /recent/feeds but…
  • GETFeed Value Blockshttps://tracking.podcastindex.org/static/tracking/feedValueBlocksGet all feeds with value blocks. Access at: https://tracking.podcastindex.org/feedValueBlocks.json
  • GETEpisode Value Blockshttps://tracking.podcastindex.org/static/tracking/episodeValueBlocksGet all episodes with value blocks. Access at: https://tracking.podcastindex.org/episodeValueBlocks.json
  • GETDead Feedshttps://public.podcastindex.org/static/public/podcastindex_dead_feeds.csvLists all feed Ids that have been marked dead in the Podcast Index database. The list is updated every X hours. A subset of stats can be retrieved using the…
  • GETFeeds Databasehttps://public.podcastindex.org/static/public/podcastindex_feeds.db.tgzCompressed database of all non-dead feeds in the Podcast Index database. Updated daily. Some attributes excluded. No episodes included. Download from:…

API details

Base URL
https://api.podcastindex.org/api/1.0
Authentication
An API key in the User-Agent header
An API key in the X-Auth-Key header
An API key in the X-Auth-Date header
An API key in the Authorization header
Operations
52 operations on 50 pathsGET 48POST 4
Main resources
Static Data 11Podcasts 9Episodes 8Recent 6Value 5Add 4Search 4Apple Replacement 2Categories 1Hub 1
Description format
OpenAPI 3.0.2, API version 1.12.1

How to test the NDEx REST API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the NDEx REST API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses an API key in the User-Agent header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Search Podcasts” (GET /search/byterm?q=batman university), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the NDEx REST API?

Download the openapi spec in [json](pi_api.json) or [yaml](pi_api.yaml) format. Overview The Podcast Index (Podcast Index LLC) is a software developer focused… It is listed under Media & content and has 52 endpoints.

Who publishes the NDEx REST API?

It is listed from Podcastindex.org's public API description (an OpenAPI document), not published by Podcastindex.org on Swastik Codes. Anyone who controls podcastindex.org can claim the profile by adding a DNS TXT record.

What is the base URL of the NDEx REST API?

Requests go to https://api.podcastindex.org/api/1.0. Endpoint paths are added to this base URL.

How do I authenticate with the NDEx REST API?

It accepts 4 methods: an API key in the User-Agent header; an API key in the X-Auth-Key header; an API key in the X-Auth-Date header; an API key in the Authorization header.

How many endpoints does the NDEx REST API have?

52 operations on 50 paths (48 GET, 4 POST). The largest groups are Static Data, Podcasts, Episodes, Recent.

Is forking the NDEx REST API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.