Sending an api request is easy. We use an Amazon style request authorization token to secure each request.
These are the required headers for each request:
"User-Agent" - Please identify the system/product you are using to make this request.
"X-Auth-Date" - The current unix epoch time as a string. 5 minute window.
"X-Auth-Key" - Your API key string.
"Authorization" - A SHA-1 hash of the X-Auth-Key, the corresponding key secret and the X-Auth-Date value concatenated as a string.
The Authorizaton header is computed with something like this (pseudo-code):
authHeader = sha1(apiKey+apiSecret+unixTime)
Note that all parameters passed should be url encoded where necessary.
These are the endpoints currently supported:
** You must be logged in for the example links below to work.
"/api/1.0/search/byterm" - Pass a search term to look for with ?q=[search terms].
Example: GET https://api.podcastindex.org/api/1.0/search/byterm?q=batman+university
This call returns all of the feeds that match the search terms in the title of the feed.
"/api/1.0/podcasts/byfeedurl" - Pass a feed url with ?url=[feed url].
Example: GET https://api.podcastindex.org/api/1.0/podcasts/byfeedurl?url=https://feeds.theincomparable.com/batmanuniversity
This call returns everything we know about the feed.
"/api/1.0/podcasts/byfeedid" - Pass a feed id with ?id=[feed id].
Example: GET https://api.podcastindex.org/api/1.0/podcasts/byfeedid?id=75075
This call returns everything we know about the feed.
"/api/1.0/podcasts/byitunesid" - Pass an itunes id with ?id=[itunes id].
Example: GET https://api.podcastindex.org/api/1.0/podcasts/byitunesid?id=1441923632
If we have an itunes id on file for a feed, then this call returns everything we know about that feed.
"/api/1.0/add/byfeedurl" - Pass a feed url with ?url=[feed url].
Example: GET https://api.podcastindex.org/api/1.0/add/byfeedurl?url=https://feeds.theincomparable.com/batmanuniversity
**This call requires a read-write api key.
This call adds a podcast to the index using it's feed url. If a feed already exists, you will get it's existing feed id returned.
"/api/1.0/episodes/byfeedurl" - Pass a feed url with ?url=[feed url].
Example: GET https://api.podcastindex.org/api/1.0/episodes/byfeedurl?url=https://feeds.theincomparable.com/batmanuniversity
This call returns all the episodes we know about for this feed, in reverse chronological order.
"/api/1.0/episodes/byfeedid" - Pass a feed id with ?id=[id].
Example: GET https://api.podcastindex.org/api/1.0/episodes/byfeedid?id=75075
This call returns all the episodes we know about for this feed, in reverse chronological order.
"/api/1.0/episodes/byitunesid" - Pass an itunes id with ?id=[itunes id].
Example: GET https://api.podcastindex.org/api/1.0/episodes/byitunesid?id=1441923632
If we have an itunes id on file for a feed, then this call returns all the episodes we know about for the feed, in reverse chronological order.
"/api/1.0/recent/episodes" - Pass the count you want with ?max=[count].
Optional: excludeString=[url encoded string] - If you pass this argument, any item containing this string will be discarded from the result set. This may, in certain cases, reduce your set size below your "max" value.
Optional: excludeBlank (bool) - If this argument is present, items with blank titles, feed images, etc. will be excluded. This is mostly for cosmetics, but having an episode in your app with a blank title, or no image is odd.
Example: GET https://api.podcastindex.org/api/1.0/recent/episodes?max=7&excludeString=church&excludeBlank
This call returns the most recent [max] number of episodes globally across the whole index, in reverse chronological order.
"/api/1.0/recent/feeds" - Pass the unix epoch of the start time with ?since=[unix epoch] and the max count you want with &max=[count].
Example: GET https://api.podcastindex.org/api/1.0/recent/feeds?since=1599108339&max=100
This call returns the most recent [max] number of feeds that have updated globally across the whole index since [since] timestamp, in reverse chronological order. The update time is based on the publish date of the most recent item, not the publish date in the feed channel itself, since that value is so often unreliable. You can consider this as a sort of "firehose" for the index. Calling this endpoint once per hour would probably give you most of what you need.
By default, all responses are in JSON format if nothing different is specified. You can ask for a different data type by adding responseType=[type] where [type] is one of the values listed below.
These are the response data types we support:
There are various optional parameters you can pass when calling API endpoints to modify the reponses. Some are boolean true by their presence (like "itunes"), while others require a value to be passed.
Here is the current list:
We give you everything we know about the feed. Here is a breakdown of the different values and their meaning. You can expect additional properties to be added going forward. We attempt to "normalize" podcast feeds into a predictable property set, to minimize the need for vendor specifics and namespaces.
{
"status": "true",
"feeds": [
{
"id": 75075,
"title": "Batman University",
"url": "https:\/\/feeds.theincomparable.com\/batmanuniversity",
"originalUrl": "https:\/\/feeds.theincomparable.com\/batmanuniversity",
"link": "https:\/\/www.theincomparable.com\/batmanuniversity\/",
"description": "Batman University is a seasonal podcast about you know who. It began with
an analysis of episodes of Batman: The Animated Series but has now expanded
to cover other series, movies, and media. Your professor is Tony Sindelar.",
"author": "Tony Sindelar",
"ownerName": "The Incomparable",
"image": "https:\/\/www.theincomparable.com\/imgs\/logos\/logo-batmanuniversity-3x.jpg",
"artwork": "https:\/\/www.theincomparable.com\/imgs\/logos\/logo-batmanuniversity-3x.jpg",
"lastUpdateTime": 1546399813,
"lastCrawlTime": 1599328949,
"lastParseTime": 1599012694,
"lastGoodHttpStatusTime": 1599328949,
"lastHttpStatus": 200,
"contentType": "application\/x-rss+xml",
"itunesId": 1441923632,
"generator": null,
"type": 0,
"dead": 0,
"crawlErrors": 0,
"parseErrors": 0
}
],
"count": 1,
"query": "batman university",
"description": "Found matching feeds."
}
Here are some examples to get you started.
PHP
//Required values
$apiKey = "UXKCGDSYGUUEVQJSYDZH";
$apiSecret = "yzJe2eE7XV-3eY576dyRZ6wXyAbndh6LUrCZ8KN|";
$apiHeaderTime = time();
//Hash them to get the Authorization token
$hash = sha1($apiKey.$apiSecret.$apiHeaderTime);
//Set the required headers
$headers = [
"User-Agent: SuperPodcastPlayer/1.3",
"X-Auth-Key: $apiKey",
"X-Auth-Date: $apiHeaderTime",
"Authorization: $hash"
];
//Make the request to an API endpoint
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,"https://api.podcastindex.org/api/1.0/search/byterm?q=bastiat");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
//Collect and show the results
$response = curl_exec ($ch);
curl_close ($ch);
echo print_r(json_decode($response), TRUE);
C#
//Required values
string apiKey = "UXKCGDSYGUUEVQJSYDZH";
string apiSecret = "yzJe2eE7XV-3eY576dyRZ6wXyAbndh6LUrCZ8KN|";
TimeSpan t = DateTime.UtcNow - new DateTime(1970, 1, 1);
int apiHeaderTime = (int)t.TotalSeconds;
//Hash them to get the Authorization token
string hash = "";
using (SHA1Managed sha1 = new SHA1Managed())
{
var hashed = sha1.ComputeHash(Encoding.UTF8.GetBytes(apiKey + apiSecret +
apiHeaderTime));
var sb = new StringBuilder(hashed.Length * 2);
foreach (byte b in hashed)
{
// can be "x2" if you want lowercase
sb.Append(b.ToString("x2"));
}
hash = sb.ToString();
}
//Create the web request and add the required headers
HttpWebRequest request =
(HttpWebRequest)WebRequest.Create("https://api.podcastindex.org/api/1.0/search/byterm?q=bastiat");
request.Headers.Add("User-Agent", "SuperPodcastPlayer/1.3");
request.Headers.Add("X-Auth-Date", apiHeaderTime.ToString());
request.Headers.Add("X-Auth-Key", apiKey);
request.Headers.Add("Authorization", hash);
//Send the request and collect/show the results
try
{
WebResponse webResponse2 = request.GetResponse();
Stream stream2 = webResponse2.GetResponseStream();
StreamReader reader2 = new StreamReader(stream2);
Console.WriteLine(reader2.ReadToEnd());
webResponse2.Close();
}
catch (Exception e)
{
Console.WriteLine("Error.");
}