openapi: 3.0.2
info:
version: 1.12.1
title: PodcastIndex.org Add Search API
termsOfService: https://github.com/Podcastindex-org/legal/blob/main/TermsOfService.md
contact:
email: info@podcastindex.org
url: https://podcastindex.org/
license:
name: MIT
url: https://github.com/Podcastindex-org/docs-api/blob/master/LICENSE
x-logo:
url: logo.svg
href: /
description: "Download the openapi spec in [json](pi_api.json) or [yaml](pi_api.yaml) format.\n\n# Overview\n\nThe Podcast Index (Podcast Index LLC) is a software developer focused partnership that provides tools and data to\nanyone who aspires to create new and exciting Podcast experiences without the heavy lifting of indexing,\naggregation and data management.\n\n# Example Code\n\nUsers have provided example code for working the API in the following languages:\n\n - [AWS Lambda - python](https://github.com/tbowers/python-podcastindex-org-lambda)\n - [Bash](https://github.com/suorcd/Bash-podcastindex-org-example)\n - [C#](https://github.com/ComicStrip/csharp-podcastindex-org-example)\n - [Elisp](https://github.com/sabexx/elisp-example)\n - [Flutter/Dart](https://github.com/crediblecreative/flutter-dart-podcastindex-org-example)\n - [Go](https://github.com/ComicStrip/Go-podcastindex-org-example)\n - [Go](https://github.com/kilobit/podcast-index-client)\n - [Java](https://github.com/ComicStrip/Java-podcastindex-org-example)\n - [Java](https://github.com/stucoates/PodcastIndexJavaClient)\n - [Node.js](https://github.com/ComicStrip/node.js-podcastindex-org-example)\n - [PHP](https://github.com/Podcastindex-org/example-code)\n - [Python](https://github.com/tbowers/python-podcastindex-org-example)\n - [Swift](https://github.com/ComicStrip/Swift-podcastindex-org-example)\n - ... [More](https://github.com/Podcastindex-org-Examples)\n\nDon't see your desired language, create an example repo and create a\n[Pull Request](https://github.com/Podcastindex-org/docs-api/pulls) with a link to your example code project!\n\n# Libraries\n\nUser created libraries for working with the API:\n\n - Java\n - [podcast4j](https://github.com/yusufyilmazfr/podcast4j)\n - .NET\n - [PodcastIndexSharp](https://www.nuget.org/packages/PodcastIndexSharp)\n - Node.js/npm/yarn\n - [podcast-index-api](https://www.npmjs.com/package/podcast-index-api)\n - [podcastdx-client](https://www.npmjs.com/package/podcastdx-client)\n - PHP\n - [podcastindex-php](https://github.com/LowSociety/podcastindex-php)\n - Python/pip\n - [python-podcastindex](https://pypi.org/project/python-podcastindex/)\n - R\n - [podindexr](https://github.com/rpodcast/podindexr)\n - Ruby\n - [podcast-index](https://github.com/jasonyork/podcast-index)\n - Swift\n - [PodcastIndexKit](https://github.com/SparrowTek/PodcastIndexKit)\n - Kotlin\n - [PodcastIndex-SDK](https://github.com/mr3y-the-programmer/PodcastIndex-SDK)\n - Go\n - [podcastindex](https://github.com/jjgmckenzie/podcastindex)\n - [podcastindex-go](https://github.com/koalahl/podcastindex-go)\n\nAre we missing a library? Did you create one for a different language? Create a\n[Pull Request](https://github.com/Podcastindex-org/docs-api/pulls) with a link to the new library!\n\n# Postman\n\nA collection file for use in the [Postman](https://www.postman.com/) application is available for this API.\n\n 1. Download the contents of the [Postman Docs](https://github.com/Podcastindex-org/docs-api/tree/master/Postman%20Docs) folder.\n 2. Import the `PodcastIndex.postman_collection.json` collection to Postman\n 3. Import the `PodcastIndexOrgEnvironment.postman_environment.json` to Postman\n 4. Click \"Environments\" on the left sidebar\n 5. Select the checkbox next to the PodcastIndexOrgEnvironment entry\n 6. Set `AuthKey` and `SeceretKey` values under the \"Current Value\" column using your API information\n 7. Click \"Collections\" from the sidebar\n 8. Select PodcastIndex\n 9. Select and run the endpoint to test\n\n# Contributing\n\nThe source for this API documentation is available at\n[https://github.com/Podcastindex-org/docs-api](https://github.com/Podcastindex-org/docs-api).\nSubmit an Issue or create a Pull Request.\n\n# Authentication Details\n\nSending an API request is easy. We use an Amazon-style request authorization token to secure each request.\n\n\nRegister for a free API key at https://api.podcastindex.org/\n\n\nThese headers parameters are required for each request: `User-Agent`, `X-Auth-Date`, `X-Auth-Key`, `Authorization`\n\n\nSee [Authentication](#auth) for description of parameters.\n\n# Legal\n\nLegal\n\n - [Privacy Policy](https://github.com/Podcastindex-org/legal/blob/main/PrivacyPolicy.md)\n - [Terms of Service](https://github.com/Podcastindex-org/legal/blob/main/TermsOfService.md)\n - [License](https://github.com/Podcastindex-org/docs-api/blob/master/LICENSE)\n"
servers:
- url: https://api.podcastindex.org/api/1.0
tags:
- name: Search
description: 'Search the index
'
paths:
/search/byterm:
get:
tags:
- Search
summary: Search Podcasts
description: 'This call returns all of the feeds that match the search terms in the `title`, `author` or `owner` of the feed.
Example: https://api.podcastindex.org/api/1.0/search/byterm?q=batman+university&pretty
'
operationId: search/byterm
security:
- API-Key: []
User-Agent: []
Date: []
Authorization: []
parameters:
- $ref: '#/components/parameters/q'
- $ref: '#/components/parameters/val'
- $ref: '#/components/parameters/max'
- $ref: '#/components/parameters/aponly'
- $ref: '#/components/parameters/clean'
- $ref: '#/components/parameters/similar'
- $ref: '#/components/parameters/fulltext'
- $ref: '#/components/parameters/pretty'
responses:
'200':
$ref: '#/components/responses/search_byterm'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
x-codeSamples:
- lang: PHP
source: "//Required values\n$apiKey = \"UXKCGDSYGUUEVQJSYDZH\";\n$apiSecret = \"yzJe2eE7XV-3eY576dyRZ6wXyAbndh6LUrCZ8KN|\";\n$apiHeaderTime = time();\n\n//Hash them to get the Authorization token\n$hash = sha1($apiKey.$apiSecret.$apiHeaderTime);\n\n//Set the required headers\n$headers = [\n \"User-Agent: SuperPodcastPlayer/1.3\",\n \"X-Auth-Key: $apiKey\",\n \"X-Auth-Date: $apiHeaderTime\",\n \"Authorization: $hash\"\n];\n\n//Make the request to an API endpoint\n$ch = curl_init();\ncurl_setopt($ch, CURLOPT_URL,\"https://api.podcastindex.org/api/1.0/search/byterm?q=bastiat\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, $headers);\n\n//Collect and show the results\n$response = curl_exec ($ch);\ncurl_close ($ch);\necho print_r(json_decode($response), TRUE);\n"
- lang: C#
source: "//Required values\nstring apiKey = \"UXKCGDSYGUUEVQJSYDZH\";\nstring apiSecret = \"yzJe2eE7XV-3eY576dyRZ6wXyAbndh6LUrCZ8KN|\";\nTimeSpan t = DateTime.UtcNow - new DateTime(1970, 1, 1);\nint apiHeaderTime = (int)t.TotalSeconds;\n\n//Hash them to get the Authorization token\nstring hash = \"\";\nusing (SHA1Managed sha1 = new SHA1Managed())\n{\n var hashed = sha1.ComputeHash(Encoding.UTF8.GetBytes(apiKey + apiSecret + apiHeaderTime));\n var sb = new StringBuilder(hashed.Length * 2);\n\n foreach (byte b in hashed)\n {\n // can be \"x2\" if you want lowercase\n sb.Append(b.ToString(\"x2\"));\n }\n\n hash = sb.ToString();\n}\n\n//Create the web request and add the required headers\nHttpWebRequest request = (HttpWebRequest)WebRequest.Create(\"https://api.podcastindex.org/api/1.0/search/byterm?q=bastiat\");\nrequest.Headers.Add(\"User-Agent\", \"SuperPodcastPlayer/1.3\");\nrequest.Headers.Add(\"X-Auth-Date\", apiHeaderTime.ToString());\nrequest.Headers.Add(\"X-Auth-Key\", apiKey);\nrequest.Headers.Add(\"Authorization\", hash);\n\n//Send the request and collect/show the results\ntry\n{\n WebResponse webResponse2 = request.GetResponse();\n Stream stream2 = webResponse2.GetResponseStream();\n StreamReader reader2 = new StreamReader(stream2);\n\n Console.WriteLine(reader2.ReadToEnd());\n\n webResponse2.Close();\n}\ncatch (Exception e)\n{\n Console.WriteLine(\"Error.\");\n}\n"
- lang: Swift
source: "import Foundation\nimport CommonCrypto\n\nextension String {\n func sha1() -> String {\n let data = Data(self.utf8)\n var digest = [UInt8](repeating: 0, count:Int(CC_SHA1_DIGEST_LENGTH))\n data.withUnsafeBytes {\n _ = CC_SHA1($0.baseAddress, CC_LONG(data.count), &digest)\n }\n let hexBytes = digest.map { String(format: \"%02hhx\", $0) }\n return hexBytes.joined()\n }\n}\n\nlet apiKey = \"UXKCGDSYGUUEVQJSYDZH\"\nlet apiSecret = \"yzJe2eE7XV-3eY576dyRZ6wXyAbndh6LUrCZ8KN|\"\nlet apiHeaderTime = String(Int(Date().timeIntervalSince1970))\nlet hash = (apiKey + apiSecret + apiHeaderTime).sha1()\n\nvar semaphore = DispatchSemaphore (value: 0)\nvar request = URLRequest(url: URL(string: \"https://api.podcastindex.org/api/1.0/search/byterm?q=bastiat\")!,timeoutInterval: Double.infinity)\nrequest.addValue(\"SuperPodcastPlayer/1.3\", forHTTPHeaderField: \"User-Agent\")\nrequest.addValue(apiKey, forHTTPHeaderField: \"X-Auth-Key\")\nrequest.addValue(apiHeaderTime, forHTTPHeaderField: \"X-Auth-Date\")\nrequest.addValue(hash, forHTTPHeaderField: \"Authorization\")\n\nrequest.httpMethod = \"GET\"\n\nlet task = URLSession.shared.dataTask(with: request) { data, response, error in\n guard let data = data else {\n print(String(describing: error))\n return\n }\n print(String(data: data, encoding: .utf8)!)\n semaphore.signal()\n}\n\ntask.resume()\nsemaphore.wait()\n"
/search/bytitle:
get:
tags:
- Search
summary: Search Podcasts by Title
description: 'This 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 podcast
[Everything Everywhere Daily](https://podcastindex.org/podcast/437685) by "everything everywhere" will not.
Example: https://api.podcastindex.org/api/1.0/search/bytitle?q=everything+everywhere+daily&pretty
'
operationId: search/bytitle
security:
- API-Key: []
User-Agent: []
Date: []
Authorization: []
parameters:
- $ref: '#/components/parameters/q'
- $ref: '#/components/parameters/val'
- $ref: '#/components/parameters/max'
- $ref: '#/components/parameters/clean'
- $ref: '#/components/parameters/fulltext'
- $ref: '#/components/parameters/pretty'
- $ref: '#/components/parameters/similar'
responses:
'200':
$ref: '#/components/responses/search_byterm'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
/search/byperson:
get:
tags:
- Search
summary: Search Episodes by Person
description: "This call returns all of the episodes where the specified person is mentioned.\n\n\nIt searches the following fields:\n\n - Person tags\n - Episode title\n - Episode description\n - Feed owner\n - Feed author\n\n\nExamples:\n\n - https://api.podcastindex.org/api/1.0/search/byperson?q=adam%20curry&pretty\n - https://api.podcastindex.org/api/1.0/search/byperson?q=Martin+Mouritzen&pretty\n - https://api.podcastindex.org/api/1.0/search/byperson?q=Klaus+Schwab&pretty\n"
operationId: search/byperson
security:
- API-Key: []
User-Agent: []
Date: []
Authorization: []
parameters:
- $ref: '#/components/parameters/q_person'
- $ref: '#/components/parameters/max'
- $ref: '#/components/parameters/fulltext'
- $ref: '#/components/parameters/pretty'
responses:
'200':
$ref: '#/components/responses/search_byperson'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
/search/music/byterm:
get:
tags:
- Search
summary: Search Music Podcasts
description: 'This call returns all of the feeds that match the search terms in the `title`, `author` or `owner` of the <feed></feed>
where the [medium](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#medium) is `music`.
Example: https://api.podcastindex.org/api/1.0/search/music/byterm?q=able+kirby&pretty
'
operationId: search/music/byterm
security:
- API-Key: []
User-Agent: []
Date: []
Authorization: []
parameters:
- $ref: '#/components/parameters/q'
- $ref: '#/components/parameters/val'
- $ref: '#/components/parameters/aponly'
- $ref: '#/components/parameters/max'
- $ref: '#/components/parameters/clean'
- $ref: '#/components/parameters/fulltext'
- $ref: '#/components/parameters/pretty'
responses:
'200':
$ref: '#/components/responses/search_byterm'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
components:
schemas:
lastGoodHttpStatusTime:
description: 'Timestamp of the last time we got a "good", meaning non-4xx/non-5xx, status code when pulling this feed from its url.
'
type: integer
format: Unix Epoch
example: 1613394034
description_episode:
description: 'The item-level description of the episode.
Uses the longer of the possible fields in the feed: `<description>`, `<itunes:summary>` and `<content:encoded>`
'
type: string
example: Batman University is back in session! James Thomson and Nathan Alderman join Tony for a discussion of Fox’s “Gotham.” Tune in to hear our thoughts on how a half-baked comic book show was reborn into an unmissable train wreck.
explicit_episode:
description: "Is feed or episode marked as explicit\n\n - 0: not marked explicit\n - 1: marked explicit\n"
type: integer
enum:
- 0
- 1
example: 0
description_response:
description: 'Description of the response
'
type: string
example: Found matching feed
season:
description: 'Season number. May be null for `liveItem`.
'
type: integer
nullable: true
example: 3
lastHttpStatus:
description: 'The last http status code we got when pulling this feed from its url.
You will see some made up status codes sometimes. These are what we use to track state within the feed puller.
These all start with 9xx.
'
type: integer
example: 200
parseErrors:
description: 'The number of errors we’ve encountered trying to parse the feed content.
Errors here are things like not well-formed xml, bad character encoding, etc.
We fix many of these types of issues on the fly when parsing.
We only increment the errors count when we can’t fix it.
'
type: integer
example: 0
language:
description: 'The channel-level language specification of the feed.
Languages accord with the [RSS Language Spec](https://www.rssboard.org/rss-language-codes).
'
type: string
example: en-us
transcriptUrl:
description: 'Link to the file containing the episode transcript
Note: in most use cases, the `transcripts` value should be used instead
'
type: string
nullable: true
format: URL
example: https://mp3s.nashownotes.com/NA-1322-Captions.srt
enclosureLength:
description: 'The length of the item specified by the `enclosureUrl` in bytes
'
type: integer
format: bytes
example: 26385472
enclosureType:
description: 'The Content-Type for the item specified by the `enclosureUrl`
'
type: string
example: audio/mp3
lastParseTime:
description: 'The last time we tried to parse the downloaded feed content.
'
type: integer
format: Unix Epoch
example: 1613394045
link_feed:
description: 'The channel-level link in the feed
'
type: string
format: URL
example: https://www.theincomparable.com/batmanuniversity/
episode_number:
description: 'Episode number
'
type: integer
nullable: true
example: 19
lastUpdateTime:
description: 'The channel-level pubDate for the feed, if it’s sane.
If not, this is a heuristic value, arrived at by analyzing other parts of the feed, like item-level pubDates.
'
type: integer
format: Unix Epoch
example: 1613394044
feed_search:
type: object
properties:
id:
$ref: '#/components/schemas/id_feed'
podcastGuid:
$ref: '#/components/schemas/podcastguid'
title:
$ref: '#/components/schemas/title_feed'
url:
$ref: '#/components/schemas/url_feed'
originalUrl:
$ref: '#/components/schemas/originalUrl'
link:
$ref: '#/components/schemas/link_feed'
description:
$ref: '#/components/schemas/description_feed'
author:
$ref: '#/components/schemas/author'
ownerName:
$ref: '#/components/schemas/ownerName'
image:
$ref: '#/components/schemas/image_feed'
artwork:
$ref: '#/components/schemas/artwork'
lastUpdateTime:
$ref: '#/components/schemas/lastUpdateTime'
lastCrawlTime:
$ref: '#/components/schemas/lastCrawlTime'
lastParseTime:
$ref: '#/components/schemas/lastParseTime'
lastGoodHttpStatusTime:
$ref: '#/components/schemas/lastGoodHttpStatusTime'
lastHttpStatus:
$ref: '#/components/schemas/lastHttpStatus'
contentType:
$ref: '#/components/schemas/contentType'
itunesId:
$ref: '#/components/schemas/itunesId_feed'
generator:
$ref: '#/components/schemas/generator'
language:
$ref: '#/components/schemas/language'
explicit:
$ref: '#/components/schemas/explicit_feed'
type:
$ref: '#/components/schemas/type'
medium:
$ref: '#/components/schemas/medium_feed'
dead:
$ref: '#/components/schemas/dead'
episodeCount:
$ref: '#/components/schemas/episodeCount'
crawlErrors:
$ref: '#/components/schemas/crawlErrors'
parseErrors:
$ref: '#/components/schemas/parseErrors'
categories:
$ref: '#/components/schemas/categories'
locked:
$ref: '#/components/schemas/locked'
imageUrlHash:
$ref: '#/components/schemas/imageUrlHash'
newestItemPubdate:
$ref: '#/components/schemas/newestItemPublishTime'
itunesId_feed:
description: 'The iTunes ID of this feed if there is one, and we know what it is.
'
type: integer
nullable: true
example: 1441923632
categories:
description: 'An array of categories, where the index is the Category ID and the value is the Category Name.
All Category numbers and names are returned by the `categories/list` endpoint.
'
type: object
example:
'104': Tv
'105': Film
'107': Reviews
description_feed:
description: 'The channel-level description
Uses the longer of the possible fields in the feed: `<description>`, `<itunes:summary>` and `<content:encoded>`
'
type: string
example: '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.'
transcripts:
description: 'List of transcripts for the episode. May not be reported.
'
type: array
nullable: true
items:
$ref: '#/components/schemas/transcript'
type:
description: "Type of source feed where:\n\n - 0: RSS\n - 1: Atom\n"
type: integer
enum:
- 0
- 1
example: 0
transcript:
description: 'This tag is used to link to a transcript or closed captions file. Multiple tags can be present for multiple transcript formats.
Detailed file format information and example files are [here](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/tags/transcript.md).
'
type: object
properties:
url:
description: URL of the podcast transcript.
type: string
format: URL
example: https://mp3s.nashownotes.com/NA-1385-Captions.srt
type:
description: 'Mime type of the file such as `text/plain`, `text/html`, `application/srt`, `text/vtt`, `application/json`
'
type: string
enum:
- application/json
- application/srt
- text/html
- text/plain
- text/srt
- text/vtt
example: application/srt
dateCrawled:
description: 'The time this episode was found in the feed
'
type: integer
format: Unix Epoch
example: 1598369047
ownerName:
description: 'The channel-level owner:name element.
Usually iTunes specific, but could be from another namespace if not present.
'
type: string
example: The Incomparable
enclosureUrl:
description: 'URL/link to the episode file
'
type: string
format: URL
example: https://www.theincomparable.com/podcast/batmanuniversity302.mp3
image_feed:
description: 'The channel-level image element.
'
type: string
format: URL
example: https://www.theincomparable.com/imgs/logos/logo-batmanuniversity-3x.jpg?cache-buster=2019-06-11
imageUrlHash:
description: 'A CRC32 hash of the `image` URL with the protocol (`http://`, `https://`) removed. 64bit integer.
'
type: integer
example: 3969216649
title_feed:
description: 'Name of the feed
'
type: string
example: Batman University
item_search_byperson:
type: object
properties:
id:
$ref: '#/components/schemas/id_episode'
title:
$ref: '#/components/schemas/title_episode'
link:
$ref: '#/components/schemas/link_feed'
description:
$ref: '#/components/schemas/description_episode'
guid:
$ref: '#/components/schemas/guid'
datePublished:
$ref: '#/components/schemas/datePublished'
dateCrawled:
$ref: '#/components/schemas/dateCrawled'
enclosureUrl:
$ref: '#/components/schemas/enclosureUrl'
enclosureType:
$ref: '#/components/schemas/enclosureType'
enclosureLength:
$ref: '#/components/schemas/enclosureLength'
duration:
$ref: '#/components/schemas/duration'
explicit:
$ref: '#/components/schemas/explicit_episode'
episode:
$ref: '#/components/schemas/episode_number'
episodeType:
$ref: '#/components/schemas/episodeType'
season:
$ref: '#/components/schemas/season'
image:
$ref: '#/components/schemas/image_episode'
feedItunesId:
$ref: '#/components/schemas/itunesId_feed'
feedImage:
$ref: '#/components/schemas/image_feed'
feedId:
$ref: '#/components/schemas/id_feed'
feedUrl:
$ref: '#/components/schemas/url_feed'
feedAuthor:
$ref: '#/components/schemas/author'
feedTitle:
$ref: '#/components/schemas/title_feed'
feedLanguage:
$ref: '#/components/schemas/language'
chaptersUrl:
$ref: '#/components/schemas/chaptersUrl'
transcriptUrl:
$ref: '#/components/schemas/transcriptUrl'
transcripts:
$ref: '#/components/schemas/transcripts'
locked:
description: "Tell other podcast platforms whether they are allowed to import this feed.\nA value of 1 means that any attempt to import this feed into a new platform should be rejected.\n\nContains the value of the feed's channel-level `podcast:locked` tag where:\n\n - 0: 'no'\n - 1: 'yes'\n"
type: integer
enum:
- 0
- 1
example: 0
items_byperson:
description: 'List of episodes matching request
'
type: array
items:
$ref: '#/components/schemas/item_search_byperson'
query_search:
description: 'Search terms passed to request
'
type: string
example: batman university
episodeCount:
description: 'Number of episodes for this feed known to the index.
'
type: integer
example: 19
contentType:
description: 'The Content-Type header from the last time we pulled this feed from its url.
'
type: string
example: application/rss+xml
count:
description: 'Number of items returned in request
'
type: integer
example: 1
generator:
description: 'The channel-level generator element if there is one.
'
type: string
example: my podcast host
id_episode:
description: 'The internal PodcastIndex.org episode ID.
'
type: integer
example: 16795088
lastCrawlTime:
description: 'The last time we attempted to pull this feed from its url.
'
type: integer
format: Unix Epoch
example: 1613394034
artwork:
description: 'The seemingly best artwork we can find for the feed.
Might be the same as `image` in most instances.
'
type: string
format: URL
example: https://www.theincomparable.com/imgs/logos/logo-batmanuniversity-3x.jpg?cache-buster=2019-06-11
explicit_feed:
description: 'Is feed marked as explicit
'
type: boolean
example: false
crawlErrors:
description: 'The number of errors we’ve encountered trying to pull a copy of the feed.
Errors are things like a 500 or 404 response, a server timeout, bad encoding, etc.
'
type: integer
example: 0
author:
description: 'The channel-level author element.
Usually iTunes specific, but could be from another namespace if not present.
'
type: string
example: Tony Sindelar
podcastguid:
description: 'The GUID from the `podcast:guid` tag in the feed. This value is a unique, global identifier for the podcast.
See the namespace spec for
[guid](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#guid) for details.
'
type: string
example: 9b024349-ccf0-5f69-a609-6b82873eab3c
newestItemPublishTime:
description: "The time the most recent episode in the feed was published.\n\n\nNote: some endpoints use `newestItemPubdate` while others use `newestItemPublishTime`. \nThey return the same information. See https://github.com/Podcastindex-org/api/issues/3 to track when the property name is updated.\n"
type: integer
format: Unix Epoch
example: 1546399813
duration:
description: 'The estimated length of the item specified by the `enclosureUrl` in seconds. Will be null for `liveItem`.
'
type: integer
nullable: true
format: seconds
example: 54
dead:
description: 'At some point, we give up trying to process a feed and mark it as dead.
This is usually after 1000 errors without a successful pull/parse cycle.
Once the feed is marked dead, we only check it once per month.
'
type: integer
example: 0
datePublished:
description: 'The date and time the episode was published
'
type: integer
format: Unix Epoch
example: 1546399813
chaptersUrl:
description: 'Link to the JSON file containing the episode chapters
'
type: string
nullable: true
format: URL
example: https://studio.hypercatcher.com/chapters/podcast/http:feed.nashownotes.comrss.xml/episode/http:1322.noagendanotes.com
guid:
description: 'The unique identifier for the episode
'
type: string
example: incomparable/batman/19
id_feed:
description: 'The internal PodcastIndex.org Feed ID.
'
type: integer
example: 75075
status:
description: 'Indicates API request status
'
type: string
enum:
- 'true'
- 'false'
example: 'true'
title_episode:
description: 'Name of the episode
'
type: string
example: Gotham
originalUrl:
description: 'The URL of the feed, before it changed to the current `url` value.
'
type: string
format: URL
example: https://feeds.theincomparable.com/batmanuniversity
episodeType:
description: 'The type of episode. May be null for `liveItem`.
'
type: string
nullable: true
enum:
- full
- trailer
- bonus
example: full
image_episode:
description: 'The item-level image for the episode
'
type: string
format: URL
example: https://www.theincomparable.com/imgs/logos/logo-batmanuniversity-3x.jpg?cache-buster=2019-06-11
url_feed:
description: 'Current feed URL
'
type: string
format: URL
example: https://feeds.theincomparable.com/batmanuniversity
medium_feed:
description: 'The value of the `podcast:medium` attribute for the feed.
See the [medium](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#medium) description in the Podcast Namespace for more information.
'
type: string
example: music
feeds:
description: 'List of feeds matching request
'
type: array
items:
$ref: '#/components/schemas/feed_search'
parameters:
clean:
name: clean
in: query
description: 'If present, only non-explicit feeds will be returned.
Meaning, feeds where the `itunes:explicit` flag is set to `false`.
Parameter shall not have a value
'
schema:
type: boolean
allowEmptyValue: true
pretty:
name: pretty
in: query
description: 'If present, makes the output “pretty” to help with debugging.
Parameter shall not have a value
'
schema:
type: boolean
allowEmptyValue: true
aponly:
name: aponly
in: query
description: 'Only returns feeds with an `itunesId`.
'
schema:
type: boolean
example: 'true'
fulltext:
name: fulltext
in: query
description: 'If present, return the full text value of any text fields (ex: `description`).
If not provided, field value is truncated to 100 words.
Parameter shall not have a value
'
schema:
type: boolean
allowEmptyValue: true
val:
name: val
in: query
description: 'Only returns feeds with a `value` block of the specified type. Use `any` to return feeds with any `value` block.
'
schema:
type: string
enum:
- any
- lightning
- hive
- webmonetization
example: ''
q:
name: q
in: query
description: 'Terms to search for
'
required: true
schema:
type: string
example: batman university
max:
name: max
in: query
description: 'Maximum number of results to return.
'
schema:
type: integer
minimum: 1
maximum: 1000
example: 10
q_person:
name: q
in: query
description: 'Person search for
'
required: true
schema:
type: string
example: adam curry
similar:
name: similar
in: query
description: 'If present, include similar matches in search response. For `search/byterm`, prioritizes title matches.
'
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/podcastindex/refs/heads/main/openapi/podcastindex-search-api-openapi.yml