PodcastIndex Apple Replacement API

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"