openapi: 3.0.2 info: version: 1.12.1 title: PodcastIndex.org Add Apple Replacement 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: Apple Replacement paths: /search: get: tags: - Apple Replacement summary: Search description: "Replaces the Apple search API but returns data from the Podcast Index database.\n\n\nNote: No API key needed for this endpoint.\n\n\nExample:\n\n - Apple: https://itunes.apple.com/search?media=podcast&entity=podcast&term=batman\n - PodcastIndex: https://api.podcastindex.org/search?term=batman\n" operationId: search security: [] servers: - url: https://api.podcastindex.org description: URL for Apple Replacement endpoints parameters: - $ref: '#/components/parameters/term_itunes' - $ref: '#/components/parameters/pretty' responses: '200': $ref: '#/components/responses/itunes_replacement' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' /lookup: get: tags: - Apple Replacement summary: Lookup description: "Replaces the Apple podcast lookup API but returns data from the Podcast Index database.\n\n\nNote: No API key needed for this endpoint.\n\n\nExample:\n\n - Apple: https://itunes.apple.com/lookup?media=podcast&entity=podcast&id=1636765656\n - PodcastIndex: https://api.podcastindex.org/lookup?entity=podcast&id=1636765656\n" operationId: lookup security: [] servers: - url: https://api.podcastindex.org description: URL for Apple Replacement endpoints parameters: - $ref: '#/components/parameters/id_feed_podcast_itunes' - $ref: '#/components/parameters/entity' - $ref: '#/components/parameters/pretty' responses: '200': $ref: '#/components/responses/itunes_replacement' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' components: schemas: description_response: description: 'Description of the response ' type: string example: Found matching feed title_feed_censored: description: 'The name of the feed. Note: Apple censors the name but PodcastIndex does not. ' type: string example: Batman University price: description: 'Price of content. Will always return 0. ' type: integer example: 0 resultCount: description: 'Number of items returned in request ' type: integer example: 1 artworkUrl: description: 'A URL for the artwork associated with the returned media type. Note: Apple returns the image sized to value in the field name but the PodcastIndex returns the original image specified in the feed. ' type: string example: https://www.theincomparable.com/imgs/logos/logo-batmanuniversity-3x.jpg title_feed: description: 'Name of the feed ' type: string example: Batman University collectionId: description: 'The iTunes Feed ID ' type: integer example: 1441923632 author: description: 'The channel-level author element. Usually iTunes specific, but could be from another namespace if not present. ' type: string example: Tony Sindelar itunes_replacement_results: description: 'List of feeds matching request ' type: array items: $ref: '#/components/schemas/itunes_results' status: description: 'Indicates API request status ' type: string enum: - 'true' - 'false' example: 'true' itunes_results: type: object properties: artistName: $ref: '#/components/schemas/author' artworkUrl100: $ref: '#/components/schemas/artworkUrl' artworkUrl30: $ref: '#/components/schemas/artworkUrl' artworkUrl60: $ref: '#/components/schemas/artworkUrl' artworkUrl600: $ref: '#/components/schemas/artworkUrl' collectionCensoredName: $ref: '#/components/schemas/title_feed_censored' collectionExplicitness: description: 'Indicates if the feed is marked explicit. ' type: string enum: - explicit - cleaned example: cleaned collectionHdPrice: $ref: '#/components/schemas/price' collectionId: $ref: '#/components/schemas/collectionId' collectionName: $ref: '#/components/schemas/title_feed' collectionPrice: $ref: '#/components/schemas/price' collectionViewUrl: $ref: '#/components/schemas/view_url' contentAdvisoryRating: description: 'Indicates if the feed is explicit or clean. ' type: string enum: - Clean - Explicit example: Clean country: description: 'The country the feed is from. Note: Right now, always returns "USA" ' type: string example: USA currency: description: 'Currency `*Price` value is in. Note: will always return "USD" ' type: string example: USD feedUrl: $ref: '#/components/schemas/url_feed' genreIds: description: 'List of ids representing the names in the `genres`. Values are determined by the IDs used in the url of genres on https://podcasts.apple.com/us/genre/podcasts/id26 ' type: array items: type: integer example: - 1309 - 26 genres: description: 'List of genre names. ' type: array items: type: string example: - TV & Film - Podcats kind: description: 'The kind of content returned by the search request. Note: will always return "podcast" ' type: string example: podcast primaryGenreName: description: 'The primary genre name. ' type: string example: '' releaseDate: description: 'Date and time of request ' type: string example: 2022-10-03T02:17:03-0500 trackCensoredName: $ref: '#/components/schemas/title_feed_censored' trackCount: description: 'Number of episodes in feed ' type: integer example: 12 trackExplicitness: description: 'Indicates if the episode is marked explicit. ' type: string enum: - explicit - cleaned example: cleaned trackHdPrice: $ref: '#/components/schemas/price' trackHdRentalPrice: $ref: '#/components/schemas/price' trackId: $ref: '#/components/schemas/collectionId' trackName: $ref: '#/components/schemas/title_feed' trackPrice: $ref: '#/components/schemas/price' trackRentalPrice: $ref: '#/components/schemas/price' trackViewUrl: $ref: '#/components/schemas/view_url' wrapperType: description: 'The name of the object returned by the search request. Note: will always return "track" ' type: string example: track url_feed: description: 'Current feed URL ' type: string format: URL example: https://feeds.theincomparable.com/batmanuniversity view_url: description: 'The URL for viewing the feed on the Apple website. ' type: string example: https://podcasts.apple.com/us/podcast/*/id1441923632?uo=4 responses: itunes_replacement: description: Success content: application/json: schema: type: object properties: resultCount: $ref: '#/components/schemas/resultCount' results: $ref: '#/components/schemas/itunes_replacement_results' '400': description: Invalid request content: application/json: schema: type: object properties: status: $ref: '#/components/schemas/status' description: $ref: '#/components/schemas/description_response' example: status: 'false' description: Invalid parameters '401': description: Not authenticated content: application/json: schema: type: string example: Authorization header value either not set or blank. parameters: entity: name: entity in: query description: 'The iTunes entity type to look in ' required: true schema: type: string enum: - podcast example: podcast 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 term_itunes: name: term in: query description: 'The term to search for ' required: true schema: type: string example: batman id_feed_podcast_itunes: name: id in: query description: 'The iTunes Feed ID to search for ' required: true schema: type: integer examples: id_only: value: 1441923632 description: iTunes ID without any prefix prefix: value: id1441923632 description: iTunes ID with optional "id" prefix securitySchemes: User-Agent: type: apiKey in: header name: User-Agent description: 'Please identify the system/product you are using to make this request. *Example*: `SuperPodcastPlayer/1.3` ' API-Key: type: apiKey in: header name: X-Auth-Key description: 'Your API key string *Example*: `UXKCGDSYGUUEVQJSYDZH` ' Date: type: apiKey in: header name: X-Auth-Date description: 'The current UTC unix epoch time as a string. 3 minute window. This value is an integer; round down if needed. The value shall not include a decimal point. Value generated should match the value shown on the website https://www.epochconverter.com/. *Example*: `1613713388` ' Authorization: type: apiKey in: header name: Authorization description: "A SHA-1 hash of the `X-Auth-Key`, the corresponding secret and the `X-Auth-Date` value concatenated as a string.\nThe resulting hash should be encoded as a hexadecimal value, two digits per byte, using lower case letters for\nthe hex digits \"a\" through \"f\".\n\n\nThe Authorization header is computed with something like this (pseudo-code):\n\n authHeader = sha1(apiKey+apiSecret+unixTime)\n\nExample value, uses example values of `X-Auth-Key` and `X-Auth-Date` and an api secret of\n`yzJe2eE7XV-3eY576dyRZ6wXyAbndh6LUrCZ8KN|`\n\n\n*Example*: `UXKCGDSYGUUEVQJSYDZH`\n"