{ "openapi": "3.0.3", "info": { "title": "iOS App Store Deep Reviews & App Intelligence (server mode)", "version": "1.1", "description": "Send one lookup and get the results back in the response. It takes the same input as a normal run: query parameters with GET, or a JSON body with POST. At most 100 results and 240 seconds per request; start a normal run for bigger jobs. Requests run in your own Apify account at the Actor's normal price.", "x-oa-server-mode": "1.1" }, "paths": { "/": { "get": { "operationId": "lookupGet", "summary": "Run one lookup (query parameters)", "parameters": [ { "name": "mode", "in": "query", "required": true, "description": "What to collect. Search finds apps by keyword, Lookup resolves IDs/URLs, Reviews collects customer feedback, Developer lists a publisher's apps, and Charts reads a top list.", "schema": { "type": "string", "enum": [ "search", "lookup", "reviews", "developer", "charts" ], "default": "search" }, "example": "search" }, { "name": "searchTerms", "in": "query", "required": false, "description": "Keywords to search for (mode=search). Each term returns up to 200 ranked apps, and results are de-duplicated across terms. (GET: repeat the parameter once per value.)", "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 3 }, "style": "form", "explode": true, "example": [ "calculator" ] }, { "name": "appIds", "in": "query", "required": false, "description": "Apps to look up or review (mode=lookup/reviews). Accepts numeric App Store IDs, bundle IDs, app URLs, and developer URLs. Separate multiple values with commas or new lines. (GET: repeat the parameter once per value.)", "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "style": "form", "explode": true }, { "name": "startUrls", "in": "query", "required": false, "description": "Paste App Store app or developer URLs (mode=lookup/reviews). App URLs resolve to one app; developer URLs expand to that publisher's catalog. (GET: repeat the parameter once per value.)", "schema": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 10 }, "style": "form", "explode": true }, { "name": "developerId", "in": "query", "required": false, "description": "Apple artist ID or developer page URL (mode=developer). For example 281956209 or https://apps.apple.com/us/developer/google/id281956209. Comma-separated values are accepted.", "schema": { "type": "string" } }, { "name": "developerName", "in": "query", "required": false, "description": "Publisher name to resolve when you do not know the developer ID (mode=developer). The actor searches App Store listings and matches the publisher name.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "Two-letter App Store storefront. Changes pricing, availability, chart contents, and review language.", "schema": { "type": "string", "enum": [ "us", "gb", "de", "fr", "jp", "in", "br", "ca", "au", "cn", "ru", "tr", "kr", "mx", "es", "it", "nl", "se", "pl", "sa", "za", "ae", "sg", "hk", "tw", "th", "id", "my", "ph", "vn", "eg", "ng", "ke", "il", "ch", "at", "be", "dk", "fi", "no", "pt", "ie", "nz", "ar", "cl", "co", "pe", "ua", "cz", "ro", "gr", "hu", "sk", "bg", "hr", "lt", "lv", "ee", "is", "lu", "mt", "cy" ], "default": "us" } }, { "name": "language", "in": "query", "required": false, "description": "Language used for App Store metadata and reviews. Defaults to English (United States).", "schema": { "type": "string", "enum": [ "en-US", "en-GB", "de-DE", "fr-FR", "es-ES", "it-IT", "ja-JP", "ko-KR", "pt-BR", "ru-RU", "zh-CN", "nl-NL", "sv-SE", "pl-PL", "tr-TR", "ar-SA" ], "default": "en-US" } }, { "name": "maxItems", "in": "query", "required": false, "description": "Hard cap on rows pushed per run (1-5000). Applies to apps, chart rows, and reviews combined. For very large review corpora, raise this and set maxReviewsPerApp.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 50 }, "example": 3 }, { "name": "maxReviewsPerApp", "in": "query", "required": false, "description": "Reviews to collect for each app (1-50000). The deep review route returns 20 per request; RSS enrichment is available for the first 500 reviews when version or helpful-vote data exists.", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 100 } }, { "name": "reviewSort", "in": "query", "required": false, "description": "Most recent first, or Apple's most-helpful ordering (mode=reviews).", "schema": { "type": "string", "enum": [ "recent", "helpful" ], "default": "recent" } }, { "name": "includeDeveloperResponses", "in": "query", "required": false, "description": "Keep developer replies when Apple exposes them (mode=reviews). Replies are available only for apps where the developer actually responded.", "schema": { "type": "boolean", "default": true }, "example": false }, { "name": "includeDetails", "in": "query", "required": false, "description": "Add App Store detail fields such as privacy labels, version history, rating histogram, support URL, and subtitle (app-producing modes). Disable it for the fastest, cheapest search runs.", "schema": { "type": "boolean", "default": true }, "example": false }, { "name": "chartType", "in": "query", "required": false, "description": "Top chart to read (mode=charts). Mac charts use the App Store Mac catalog.", "schema": { "type": "string", "enum": [ "top-free", "top-paid", "top-grossing", "top-free-ipad", "top-paid-ipad", "top-free-mac" ], "default": "top-free" } }, { "name": "proxyConfiguration", "in": "query", "required": false, "description": "Optional. The actor works without a proxy. Add an Apify Proxy configuration only if your own network or a future Apple rate limit needs it. (GET: pass it as JSON.)", "content": { "application/json": { "schema": { "type": "object", "default": { "useApifyProxy": false } } } } } ], "responses": { "200": { "description": "The results as a JSON array (at most 100). They are also saved to the run's dataset and billed per result, like a normal run.", "headers": { "X-Item-Count": { "schema": { "type": "integer" }, "description": "Results returned." }, "X-Status-Message": { "schema": { "type": "string" }, "description": "The Actor's last status message, e.g. why nothing was found." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "example": [ { "id": "1069511488", "appId": "1069511488", "bundleId": "com.apple.calculator", "name": "Calculator", "developer": "Apple Inc.", "developerId": "284417353", "developerUrl": "https://apps.apple.com/us/developer/apple/id284417353?mt=12&uo=4", "developerWebsite": "https://www.apple.com/ipados/ipados-18", "price": 0, "isFree": true, "formattedPrice": "Free", "currency": "USD", "rating": 3.06, "ratingCount": 10002, "currentVersionRating": 3.06, "currentVersionRatingCount": 10002, "description": "Calculator\n\nEasily type out math with the basic and scientific calculators for quick solutions. With the Math Notes calculator, solving expressions, creating...", "releaseNotes": "Bug Fixes and Feature Enhancements", "version": "2.7", "releaseDate": "2016-05-10T18:17:10Z", "lastUpdated": "2026-10-19T20:43:56Z", "category": "Utilities", "genres": [ "Utilities" ], "contentRating": "4+", "minimumOs": "10.0", "fileSize": "17395712", "size": 17395712, "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/f4/35/37/f435379c-2c09-a52a-1bbc-326d8cd54853/calculatorCalistoga-0-0-1x_U007epad-0-1-0-85-220.png/512x...", "screenshots": [ "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/f0/b9/70/f0b97005-c9b5-87dd-808c-80a9e5cdd78a/iOS_Calculator_App_Store_Screenshots_2026.001.jpeg/...", "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/ff/89/86/ff898691-ee97-c122-af5d-d8765270a927/iOS_Calculator_App_Store_Screenshots_2026.002.jpeg/...", "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/6b/3b/15/6b3b1511-b4b8-ac4c-db5e-79b5617f65cb/iOS_Calculator_App_Store_Screenshots_2026.003.jpeg/..." ], "ipadScreenshots": [ "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/7e/05/ba/7e05ba5b-fc6d-373c-cc3c-1ff665268761/iPadOS_Calculator_App_Store_Screenshot_2026.001.jpe...", "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/c5/ac/e2/c5ace2af-1ab9-4222-d071-988a2e1614a5/iPadOS_Calculator_App_Store_Screenshot_2026.002.jpe...", "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/8a/c3/d1/8ac3d123-83c1-91c9-48bd-cd7c61c9e075/iPadOS_Calculator_App_Store_Screenshot_2026.004.jpe..." ], "languages": [ "AR", "CA", "HR" ], "url": "https://apps.apple.com/us/app/calculator/id1069511488?uo=4", "sourceUrl": "https://apps.apple.com/us/app/calculator/id1069511488?uo=4", "recordType": "app", "searchTerm": "calculator", "searchRank": 1, "country": "us", "language": "en-US", "scrapedAt": "2026-11-10T15:32:56.676551+00:00" } ] } } }, "400": { "description": "Invalid, missing or unknown input fields. Nothing ran.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_input", "errorDescription": "mode: required" } } } }, "422": { "description": "The Actor could not complete this request (for example, nothing matches). No results were delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure. Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The request used up its 240 s budget. The results found so far are in partialItems.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "partialItems": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } } ] } } } } } }, "post": { "operationId": "lookupPost", "summary": "Run one lookup (JSON body)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "search", "lookup", "reviews", "developer", "charts" ], "default": "search", "description": "What to collect. Search finds apps by keyword, Lookup resolves IDs/URLs, Reviews collects customer feedback, Developer lists a publisher's apps, and Charts reads a top list." }, "searchTerms": { "type": "array", "items": { "type": "string" }, "maxItems": 3, "description": "Keywords to search for (mode=search). Each term returns up to 200 ranked apps, and results are de-duplicated across terms." }, "appIds": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Apps to look up or review (mode=lookup/reviews). Accepts numeric App Store IDs, bundle IDs, app URLs, and developer URLs. Separate multiple values with commas or new lines." }, "startUrls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] }, "maxItems": 10, "description": "Paste App Store app or developer URLs (mode=lookup/reviews). App URLs resolve to one app; developer URLs expand to that publisher's catalog." }, "developerId": { "type": "string", "description": "Apple artist ID or developer page URL (mode=developer). For example 281956209 or https://apps.apple.com/us/developer/google/id281956209. Comma-separated values are accepted." }, "developerName": { "type": "string", "description": "Publisher name to resolve when you do not know the developer ID (mode=developer). The actor searches App Store listings and matches the publisher name." }, "country": { "type": "string", "enum": [ "us", "gb", "de", "fr", "jp", "in", "br", "ca", "au", "cn", "ru", "tr", "kr", "mx", "es", "it", "nl", "se", "pl", "sa", "za", "ae", "sg", "hk", "tw", "th", "id", "my", "ph", "vn", "eg", "ng", "ke", "il", "ch", "at", "be", "dk", "fi", "no", "pt", "ie", "nz", "ar", "cl", "co", "pe", "ua", "cz", "ro", "gr", "hu", "sk", "bg", "hr", "lt", "lv", "ee", "is", "lu", "mt", "cy" ], "default": "us", "description": "Two-letter App Store storefront. Changes pricing, availability, chart contents, and review language." }, "language": { "type": "string", "enum": [ "en-US", "en-GB", "de-DE", "fr-FR", "es-ES", "it-IT", "ja-JP", "ko-KR", "pt-BR", "ru-RU", "zh-CN", "nl-NL", "sv-SE", "pl-PL", "tr-TR", "ar-SA" ], "default": "en-US", "description": "Language used for App Store metadata and reviews. Defaults to English (United States)." }, "maxItems": { "type": "integer", "default": 50, "minimum": 1, "maximum": 50, "description": "Hard cap on rows pushed per run (1-5000). Applies to apps, chart rows, and reviews combined. For very large review corpora, raise this and set maxReviewsPerApp." }, "maxReviewsPerApp": { "type": "integer", "default": 100, "minimum": 1, "maximum": 100, "description": "Reviews to collect for each app (1-50000). The deep review route returns 20 per request; RSS enrichment is available for the first 500 reviews when version or helpful-vote data exists." }, "reviewSort": { "type": "string", "enum": [ "recent", "helpful" ], "default": "recent", "description": "Most recent first, or Apple's most-helpful ordering (mode=reviews)." }, "includeDeveloperResponses": { "type": "boolean", "default": true, "description": "Keep developer replies when Apple exposes them (mode=reviews). Replies are available only for apps where the developer actually responded." }, "includeDetails": { "type": "boolean", "default": true, "description": "Add App Store detail fields such as privacy labels, version history, rating histogram, support URL, and subtitle (app-producing modes). Disable it for the fastest, cheapest search runs." }, "chartType": { "type": "string", "enum": [ "top-free", "top-paid", "top-grossing", "top-free-ipad", "top-paid-ipad", "top-free-mac" ], "default": "top-free", "description": "Top chart to read (mode=charts). Mac charts use the App Store Mac catalog." }, "proxyConfiguration": { "type": "object", "default": { "useApifyProxy": false }, "description": "Optional. The actor works without a proxy. Add an Apify Proxy configuration only if your own network or a future Apple rate limit needs it." } }, "additionalProperties": false, "required": [ "mode" ] }, "example": { "mode": "search", "searchTerms": [ "calculator" ], "maxItems": 3, "includeDetails": false, "includeDeveloperResponses": false } } } }, "responses": { "200": { "description": "The results as a JSON array (at most 100). They are also saved to the run's dataset and billed per result, like a normal run.", "headers": { "X-Item-Count": { "schema": { "type": "integer" }, "description": "Results returned." }, "X-Status-Message": { "schema": { "type": "string" }, "description": "The Actor's last status message, e.g. why nothing was found." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "example": [ { "id": "1069511488", "appId": "1069511488", "bundleId": "com.apple.calculator", "name": "Calculator", "developer": "Apple Inc.", "developerId": "284417353", "developerUrl": "https://apps.apple.com/us/developer/apple/id284417353?mt=12&uo=4", "developerWebsite": "https://www.apple.com/ipados/ipados-18", "price": 0, "isFree": true, "formattedPrice": "Free", "currency": "USD", "rating": 3.06, "ratingCount": 10002, "currentVersionRating": 3.06, "currentVersionRatingCount": 10002, "description": "Calculator\n\nEasily type out math with the basic and scientific calculators for quick solutions. With the Math Notes calculator, solving expressions, creating...", "releaseNotes": "Bug Fixes and Feature Enhancements", "version": "2.7", "releaseDate": "2016-05-10T18:17:10Z", "lastUpdated": "2026-10-19T20:43:56Z", "category": "Utilities", "genres": [ "Utilities" ], "contentRating": "4+", "minimumOs": "10.0", "fileSize": "17395712", "size": 17395712, "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/f4/35/37/f435379c-2c09-a52a-1bbc-326d8cd54853/calculatorCalistoga-0-0-1x_U007epad-0-1-0-85-220.png/512x...", "screenshots": [ "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/f0/b9/70/f0b97005-c9b5-87dd-808c-80a9e5cdd78a/iOS_Calculator_App_Store_Screenshots_2026.001.jpeg/...", "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/ff/89/86/ff898691-ee97-c122-af5d-d8765270a927/iOS_Calculator_App_Store_Screenshots_2026.002.jpeg/...", "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/6b/3b/15/6b3b1511-b4b8-ac4c-db5e-79b5617f65cb/iOS_Calculator_App_Store_Screenshots_2026.003.jpeg/..." ], "ipadScreenshots": [ "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/7e/05/ba/7e05ba5b-fc6d-373c-cc3c-1ff665268761/iPadOS_Calculator_App_Store_Screenshot_2026.001.jpe...", "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/c5/ac/e2/c5ace2af-1ab9-4222-d071-988a2e1614a5/iPadOS_Calculator_App_Store_Screenshot_2026.002.jpe...", "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/8a/c3/d1/8ac3d123-83c1-91c9-48bd-cd7c61c9e075/iPadOS_Calculator_App_Store_Screenshot_2026.004.jpe..." ], "languages": [ "AR", "CA", "HR" ], "url": "https://apps.apple.com/us/app/calculator/id1069511488?uo=4", "sourceUrl": "https://apps.apple.com/us/app/calculator/id1069511488?uo=4", "recordType": "app", "searchTerm": "calculator", "searchRank": 1, "country": "us", "language": "en-US", "scrapedAt": "2026-11-10T15:32:56.676551+00:00" } ] } } }, "400": { "description": "Invalid, missing or unknown input fields. Nothing ran.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_input", "errorDescription": "mode: required" } } } }, "422": { "description": "The Actor could not complete this request (for example, nothing matches). No results were delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure. Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The request used up its 240 s budget. The results found so far are in partialItems.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "partialItems": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } } ] } } } } } } } }, "components": { "schemas": { "Item": { "type": "object", "description": "One result, the same record a normal run saves to its dataset.", "properties": { "id": { "type": "string" }, "appId": { "type": "string" }, "bundleId": { "type": "string" }, "name": { "type": "string" }, "developer": { "type": "string" }, "developerId": { "type": "string" }, "developerUrl": { "type": "string" }, "developerWebsite": { "type": "string" }, "price": { "type": "number" }, "isFree": { "type": "boolean" }, "formattedPrice": { "type": "string" }, "currency": { "type": "string" }, "rating": { "type": "number" }, "ratingCount": { "type": "integer" }, "currentVersionRating": { "type": "number" }, "currentVersionRatingCount": { "type": "integer" }, "description": { "type": "string" }, "releaseNotes": { "type": "string" }, "version": { "type": "string" }, "releaseDate": { "type": "string" }, "lastUpdated": { "type": "string" }, "category": { "type": "string" }, "genres": { "type": "array", "items": { "type": "string" } }, "contentRating": { "type": "string" }, "minimumOs": { "type": "string" }, "fileSize": { "type": "string" }, "size": { "type": "integer" }, "icon": { "type": "string" }, "screenshots": { "type": "array", "items": { "type": "string" } }, "ipadScreenshots": { "type": "array", "items": { "type": "string" } }, "languages": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "sourceUrl": { "type": "string" }, "recordType": { "type": "string" }, "searchTerm": { "type": "string" }, "searchRank": { "type": "integer" }, "country": { "type": "string" }, "language": { "type": "string" }, "scrapedAt": { "type": "string" } }, "example": { "id": "1069511488", "appId": "1069511488", "bundleId": "com.apple.calculator", "name": "Calculator", "developer": "Apple Inc.", "developerId": "284417353", "developerUrl": "https://apps.apple.com/us/developer/apple/id284417353?mt=12&uo=4", "developerWebsite": "https://www.apple.com/ipados/ipados-18", "price": 0, "isFree": true, "formattedPrice": "Free", "currency": "USD", "rating": 3.06, "ratingCount": 10002, "currentVersionRating": 3.06, "currentVersionRatingCount": 10002, "description": "Calculator\n\nEasily type out math with the basic and scientific calculators for quick solutions. With the Math Notes calculator, solving expressions, creating...", "releaseNotes": "Bug Fixes and Feature Enhancements", "version": "2.7", "releaseDate": "2016-05-10T18:17:10Z", "lastUpdated": "2026-10-19T20:43:56Z", "category": "Utilities", "genres": [ "Utilities" ], "contentRating": "4+", "minimumOs": "10.0", "fileSize": "17395712", "size": 17395712, "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/f4/35/37/f435379c-2c09-a52a-1bbc-326d8cd54853/calculatorCalistoga-0-0-1x_U007epad-0-1-0-85-220.png/512x...", "screenshots": [ "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/f0/b9/70/f0b97005-c9b5-87dd-808c-80a9e5cdd78a/iOS_Calculator_App_Store_Screenshots_2026.001.jpeg/...", "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/ff/89/86/ff898691-ee97-c122-af5d-d8765270a927/iOS_Calculator_App_Store_Screenshots_2026.002.jpeg/...", "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/6b/3b/15/6b3b1511-b4b8-ac4c-db5e-79b5617f65cb/iOS_Calculator_App_Store_Screenshots_2026.003.jpeg/..." ], "ipadScreenshots": [ "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/7e/05/ba/7e05ba5b-fc6d-373c-cc3c-1ff665268761/iPadOS_Calculator_App_Store_Screenshot_2026.001.jpe...", "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/c5/ac/e2/c5ace2af-1ab9-4222-d071-988a2e1614a5/iPadOS_Calculator_App_Store_Screenshot_2026.002.jpe...", "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/8a/c3/d1/8ac3d123-83c1-91c9-48bd-cd7c61c9e075/iPadOS_Calculator_App_Store_Screenshot_2026.004.jpe..." ], "languages": [ "AR", "CA", "HR" ], "url": "https://apps.apple.com/us/app/calculator/id1069511488?uo=4", "sourceUrl": "https://apps.apple.com/us/app/calculator/id1069511488?uo=4", "recordType": "app", "searchTerm": "calculator", "searchRank": 1, "country": "us", "language": "en-US", "scrapedAt": "2026-11-10T15:32:56.676551+00:00" } }, "Error": { "type": "object", "required": [ "error", "errorDescription" ], "properties": { "error": { "type": "string", "enum": [ "invalid_input", "request_failed", "internal_error", "timeout", "busy", "not_found", "method_not_allowed", "payload_too_large" ] }, "errorDescription": { "type": "string" } } } }, "securitySchemes": { "apifyToken": { "type": "http", "scheme": "bearer", "description": "Your Apify API token (Apify Console, Settings, API and integrations)." } } }, "servers": [ { "url": "https://nimbryxo-studio--app-store-search-lookup-and-reviews-scraper.apify.actor" } ], "security": [ { "apifyToken": [] } ] }