{ "openapi": "3.0.1", "info": { "title": "Apple App Store Reviews API | iOS & macOS JSON", "description": "Apple App Store Reviews API. Fetch iOS and macOS app reviews on demand as structured JSON: ratings, titles, text, dates, versions, author, and helpfulness across 50+ country stores. Sort by most recent, most helpful, favorable, or critical. Built for ASO, sentiment, and AI agent workflows.", "version": "0.1", "x-build-id": "O6WZlyb1OjwleZX7T" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/johnvc~apple-app-store-reviews-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-johnvc-apple-app-store-reviews-api", "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/johnvc~apple-app-store-reviews-api/runs": { "post": { "operationId": "runs-sync-johnvc-apple-app-store-reviews-api", "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/johnvc~apple-app-store-reviews-api/run-sync": { "post": { "operationId": "run-sync-johnvc-apple-app-store-reviews-api", "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": { "product_ids": { "title": "Apple Product IDs", "type": "array", "description": "Numeric Apple App Store product IDs (e.g. ['534220544', '363590051']) or full App Store links. Find each ID in the App Store URL: apps.apple.com//app//id. A link's store is used when Country Store is left at 'us'. Entries that are not app IDs are skipped and never charged. Multiple IDs are fetched sequentially in one run. Either this or app_name must be provided.", "items": { "type": "string" } }, "app_name": { "title": "App Name (Auto-Resolve)", "type": "string", "description": "Free-form Apple app name to look up automatically (e.g. 'netflix', 'spotify', 'todoist'). If product_ids is empty, the actor calls the App Store search engine first and reviews the top match. Convenient for AI agents that only know an app by name. Use product_ids for exact targeting." }, "country": { "title": "Country Store", "enum": [ "us", "gb", "ca", "au", "nz", "ie", "in", "sg", "ph", "my", "de", "fr", "es", "it", "nl", "be", "at", "ch", "se", "no", "dk", "fi", "pt", "pl", "cz", "gr", "hu", "ro", "tr", "ru", "ua", "il", "ae", "sa", "eg", "za", "ng", "ke", "gh", "jp", "kr", "cn", "tw", "hk", "th", "id", "vn", "br", "mx", "ar", "cl", "co", "pe" ], "type": "string", "description": "Two-letter Apple country store code (e.g. 'us', 'gb', 'jp'). Drives both the storefront and the locale of review text and dates. Defaults to 'us'.", "default": "us" }, "sort": { "title": "Sort Order", "enum": [ "mostrecent", "mosthelpful", "mostfavorable", "mostcritical" ], "type": "string", "description": "Order reviews by recency, helpfulness votes, or rating polarity. macOS apps support most recent and most helpful; for the two rating sorts Apple returns macOS reviews in most-recent order. From November 11, 2026, iOS reviews in the most favorable or most critical sort bill on the rating-sorted-review event.", "default": "mostrecent" }, "max_reviews": { "title": "Maximum Reviews per App", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Hard cap on reviews returned per product ID. Default 100. Set 0 for unlimited (internally capped at 50 pages, about 1250 reviews on iOS or 500 on macOS). Pages contain about 25 reviews each on iOS and 10 on macOS.", "default": 100 }, "start_page": { "title": "Start Page", "minimum": 1, "maximum": 500, "type": "integer", "description": "Page number to start paginating from (1-based). Useful for resuming a long run. Defaults to 1.", "default": 1 }, "include_macos": { "title": "Include macOS Apps", "type": "boolean", "description": "Set false to skip macOS apps entirely (no reviews pushed, no charges incurred for any macOS product_id). Defaults to true (iOS and macOS both included).", "default": true }, "normalize_dates": { "title": "Normalize Review Dates to ISO", "type": "boolean", "description": "Emit a review_date_iso field alongside the locale-formatted review_date (e.g. '2021-06-02' alongside 'Jun 02, 2021'). Best-effort parsing; falls back to null when the source format is unfamiliar. Defaults to true.", "default": true }, "parse_helpfulness": { "title": "Parse Helpfulness Counts", "type": "boolean", "description": "Extract integer helpful_count and total_helpful_count fields from the prose 'X out of Y customers found this review helpful' string. Defaults to true.", "default": true }, "output_file": { "title": "Local Output File", "type": "string", "description": "Optional filename to save a local JSON copy of the API response. Used during local testing only; ignored when running on the Apify platform. Auto-generated if blank." } } }, "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 } } } } } } } } } }