{
  "openapi": "3.0.1",
  "info": {
    "title": "Apple Podcasts Scraper: Ratings, Episodes, Reviews & Charts",
    "description": "Scrape Apple Podcasts: show details with star rating and 5-star breakdown, hosts, related shows and publishing stats; full episode lists from RSS; reviews from up to 89 country stores; Top charts by country and genre with rank changes. Pay per row, hard spend caps.",
    "version": "1.1",
    "x-build-id": "8QI88fO3eOtHAVqfa"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/hydrocore~apple-podcasts-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-hydrocore-apple-podcasts-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/hydrocore~apple-podcasts-scraper/runs": {
      "post": {
        "operationId": "runs-sync-hydrocore-apple-podcasts-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/hydrocore~apple-podcasts-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-hydrocore-apple-podcasts-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "podcasts": {
            "title": "Podcasts",
            "type": "array",
            "description": "One podcast per line. Use an Apple Podcasts link (https://podcasts.apple.com/us/podcast/the-daily/id1200361736), an Apple podcast ID (1200361736), an RSS feed URL (https://feeds.npr.org/510289/podcast.xml) or a podcast name (Hardcore History). Names are looked up with Apple's search and the exact title match is preferred; the run log shows which show was picked. RSS feeds are matched back to Apple automatically when possible, so ratings and reviews still work. The same show listed twice is collected once.",
            "items": {
              "type": "string"
            }
          },
          "searchTerms": {
            "title": "Search Apple Podcasts",
            "type": "array",
            "description": "Find podcasts by keyword (for example: woodworking, true crime, AI startups). Each search saves one show record per podcast found, ranked as in Apple's search. Good for building lists of shows in a niche.",
            "items": {
              "type": "string"
            }
          },
          "maxSearchResults": {
            "title": "Max podcasts per search",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "How many podcasts to keep from each search (Apple returns at most 200).",
            "default": 25
          },
          "chartCountries": {
            "title": "Top charts: countries",
            "type": "array",
            "description": "Two-letter Apple store codes (us, gb, ca, au, de, fr, jp ...) whose Top Shows chart you want. Leave empty for no charts. Each chart position is one \"Chart entry\" row.",
            "items": {
              "type": "string"
            }
          },
          "chartGenres": {
            "title": "Top charts: genres",
            "type": "array",
            "description": "Which charts to read for every country: the overall chart (All podcasts) and/or genre charts such as Comedy or True Crime. Genre charts are available for \"Top shows\" only.",
            "items": {
              "type": "string",
              "enum": [
                "all",
                "arts",
                "business",
                "comedy",
                "education",
                "fiction",
                "government",
                "health-fitness",
                "history",
                "kids-family",
                "leisure",
                "music",
                "news",
                "religion-spirituality",
                "science",
                "society-culture",
                "sports",
                "technology",
                "true-crime",
                "tv-film"
              ],
              "enumTitles": [
                "All podcasts",
                "Arts",
                "Business",
                "Comedy",
                "Education",
                "Fiction",
                "Government",
                "Health & Fitness",
                "History",
                "Kids & Family",
                "Leisure",
                "Music",
                "News",
                "Religion & Spirituality",
                "Science",
                "Society & Culture",
                "Sports",
                "Technology",
                "True Crime",
                "TV & Film"
              ]
            },
            "default": [
              "all"
            ]
          },
          "chartType": {
            "title": "Chart type",
            "enum": [
              "top",
              "top-subscriber"
            ],
            "type": "string",
            "description": "\"Top shows\" is the main Apple Podcasts chart. \"Top subscriber shows\" ranks shows with Apple Podcasts Subscriptions.",
            "default": "top"
          },
          "chartSize": {
            "title": "Chart positions",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "How many positions to save per chart (top 10, top 50 ... up to 200; Top subscriber shows stop at 100).",
            "default": 100
          },
          "trackChartChanges": {
            "title": "Track rank changes between runs",
            "type": "boolean",
            "description": "Remember each chart in a named key-value store (apple-podcasts-chart-history) in your account and add previous rank, rank change and movement (new, up, down, same) to every chart entry. Shows that dropped out are listed in the run summary. Schedule the Actor daily to get a ranking history.",
            "default": true
          },
          "chartShowRecords": {
            "title": "Also save a show record for every charted show",
            "type": "boolean",
            "description": "Save a full show record (ratings, hosts, feed stats ...) for every show on the charts. Each one is charged as a \"Show record\".",
            "default": false
          },
          "showDetails": {
            "title": "Show record detail",
            "enum": [
              "full",
              "basic",
              "none"
            ],
            "type": "string",
            "description": "What to save for each podcast you list (and for search results). Full adds the star-rating average, rating count and 5-star histogram, hosts, channel, related shows and publishing stats from the RSS feed (frequency, active or not, hosting provider, transcripts). Every show record costs the same.",
            "default": "full"
          },
          "country": {
            "title": "Apple store country",
            "type": "string",
            "description": "Two-letter store code used for searches, names and Apple IDs (us, gb, de ...). Apple links that contain a country (podcasts.apple.com/gb/...) use their own country.",
            "default": "us"
          },
          "maxEpisodesPerShow": {
            "title": "Max episodes per show",
            "minimum": 0,
            "maximum": 100000,
            "type": "integer",
            "description": "Newest episodes first, read from the show's public RSS feed (the full back catalog, not just Apple's latest 200), with Apple episode IDs and links added. 0 = no episodes.",
            "default": 0
          },
          "since": {
            "title": "Only items published on or after",
            "type": "string",
            "description": "Optional. Episodes and reviews older than this date are skipped for free. Example: 2026-01-01."
          },
          "lastDays": {
            "title": "...or only the last N days",
            "minimum": 0,
            "maximum": 36500,
            "type": "integer",
            "description": "Optional alternative to the date above (handy for scheduled runs): only episodes and reviews from the last N days. 0 = off. If both are set, the later date wins.",
            "default": 0
          },
          "includeEpisodeHtml": {
            "title": "Include episode HTML description",
            "type": "boolean",
            "description": "Also save the original HTML show notes (with links). The plain-text description is always included.",
            "default": false
          },
          "maxReviewsPerShow": {
            "title": "Max reviews per show",
            "minimum": 0,
            "maximum": 100000,
            "type": "integer",
            "description": "Apple publishes up to 500 recent written reviews per show per country store. Add more countries below to go beyond 500. 0 = no reviews.",
            "default": 0
          },
          "reviewCountries": {
            "title": "Review countries",
            "type": "array",
            "description": "Apple store codes to read reviews from, in order (us, gb, ca, au, in ...). Use \"all\" for all 89 stores that publish reviews (slower: about 1 second per store). Each review appears once even if it shows up in several stores.",
            "default": [
              "us"
            ],
            "items": {
              "type": "string"
            }
          },
          "reviewSort": {
            "title": "Review order",
            "enum": [
              "mostrecent",
              "mosthelpful"
            ],
            "type": "string",
            "description": "Newest first works best with the date filter (the Actor stops reading once reviews get too old).",
            "default": "mostrecent"
          },
          "minStars": {
            "title": "Minimum stars",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Only save reviews with at least this many stars. Reviews outside the range are skipped for free. To get only complaints, set Minimum stars 1 and Maximum stars 2.",
            "default": 1
          },
          "maxStars": {
            "title": "Maximum stars",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Only save reviews with at most this many stars. To get only complaints, set Minimum stars 1 and Maximum stars 2.",
            "default": 5
          },
          "collectForFoundShows": {
            "title": "Also get episodes and reviews for search and chart results",
            "type": "boolean",
            "description": "Apply the episode and review limits above to every show found by search or charts too, not only to the podcasts you listed. Can add many rows: check your limits.",
            "default": false
          },
          "maxRowsTotal": {
            "title": "Max rows in total",
            "minimum": 0,
            "type": "integer",
            "description": "Optional hard limit on saved rows for the whole run. 0 = no limit.",
            "default": 0
          },
          "maxSpendUsd": {
            "title": "Max spend for this run (USD)",
            "type": "string",
            "description": "Optional, for example 1.50. The run stops before going over it. Apify's own \"Maximum cost per run\" run option is respected too; the lower of the two applies. Leave empty for no extra limit."
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}