{ "openapi": "3.0.1", "info": { "title": "App Stores Scraper - Apple App Store & Google Play ASO", "description": "Scrape Apple App Store and Google Play in one run: app details, reviews, keyword search, top charts, ASO keyword ranks, developer catalogs, and monitors. Cross-store app pairs, multi-country. Fast HTTP — no browser.", "version": "0.1", "x-build-id": "OSjZFcdbXxXAoLGUR" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawloop~app-stores-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawloop-app-stores-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/crawloop~app-stores-scraper/runs": { "post": { "operationId": "runs-sync-crawloop-app-stores-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/crawloop~app-stores-scraper/run-sync": { "post": { "operationId": "run-sync-crawloop-app-stores-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", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "app_details", "reviews", "search", "top_charts", "search_and_charts", "developer_apps", "keyword_ranks", "monitor" ], "type": "string", "description": "ASO / intelligence mode. Runs on every selected store that supports the inputs you provide.", "default": "app_details" }, "stores": { "title": "Stores", "type": "array", "description": "Which stores to scrape this run. Empty = both (apple + google).", "default": [ "apple", "google" ], "items": { "type": "string" } }, "startUrls": { "title": "Start URLs", "type": "array", "description": "App Store or Google Play URLs (apps, developers, search). Store is auto-detected from the host.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "appPairs": { "title": "Cross-store app pairs (ASO)", "type": "array", "description": "Map the same product on both stores. Each object: name/pairKey, appleId (numeric), googleId (package). Rows get pairKey stamped." }, "appleAppIds": { "title": "Apple app IDs", "type": "array", "description": "Numeric App Store track IDs (e.g. 310633997).", "default": [], "items": { "type": "string" } }, "googleAppIds": { "title": "Google Play app IDs", "type": "array", "description": "Android package names (e.g. com.whatsapp).", "default": [], "items": { "type": "string" } }, "appIds": { "title": "App IDs (auto)", "type": "array", "description": "Mixed IDs: numeric → Apple, package-like → Google. Prefer appleAppIds / googleAppIds / appPairs when possible.", "default": [], "items": { "type": "string" } }, "searchTerms": { "title": "Search / ASO keywords", "type": "array", "description": "Keywords for search, search_and_charts, and keyword_ranks.", "items": { "type": "string" } }, "searchTerm": { "title": "Search term (single)", "type": "string", "description": "Optional single keyword merged into searchTerms.", "default": "" }, "trackAppleAppIds": { "title": "Track Apple IDs (keyword ranks)", "type": "array", "description": "Apple apps to locate in SERP for keyword_ranks. Defaults to appleAppIds / pairs.", "default": [], "items": { "type": "string" } }, "trackGoogleAppIds": { "title": "Track Google IDs (keyword ranks)", "type": "array", "description": "Play packages to locate in SERP for keyword_ranks. Defaults to googleAppIds / pairs.", "default": [], "items": { "type": "string" } }, "appleDeveloperIds": { "title": "Apple developer IDs", "type": "array", "description": "Numeric artist / developer IDs for Apple developer_apps.", "default": [], "items": { "type": "string" } }, "googleDeveloperId": { "title": "Google developer ID / name", "type": "string", "description": "Play developer page id (e.g. Spotify AB).", "default": "" }, "googleDeveloperUrl": { "title": "Google developer URL", "type": "string", "description": "Full Play developer URL (overrides googleDeveloperId).", "default": "" }, "country": { "title": "Country", "type": "string", "description": "Primary storefront / gl (ISO-2).", "default": "us" }, "countries": { "title": "Countries", "type": "array", "description": "Multi-country storefronts. Use \"all\" for Apple major-storefronts preset. For Play, combined with languages.", "default": [], "items": { "type": "string" } }, "useAllCountries": { "title": "Use all major Apple countries", "type": "boolean", "description": "Apple only: scrape the built-in major storefronts list (~44).", "default": false }, "language": { "title": "Language (Play hl)", "type": "string", "description": "Primary Google Play language.", "default": "en" }, "languages": { "title": "Languages (Play multi)", "type": "array", "description": "Optional Play hl codes × countries (cartesian, capped).", "default": [], "items": { "type": "string" } }, "appleChartType": { "title": "Apple chart type", "enum": [ "top_free", "top_paid", "top_grossing", "new_free", "new_paid", "new_apps" ], "type": "string", "description": "App Store top charts feed.", "default": "top_free" }, "googleChartType": { "title": "Google chart type", "enum": [ "", "topselling_free", "topselling_paid", "topgrossing" ], "type": "string", "description": "Play top chart collection.", "default": "topselling_free" }, "appleGenreId": { "title": "Apple genre ID", "type": "integer", "description": "Optional App Store genre for charts (e.g. 6014 Games)." }, "googleCategory": { "title": "Google Play category", "type": "string", "description": "Play category id (e.g. GAME_ACTION, MUSIC_AND_AUDIO).", "default": "" }, "chartLimit": { "title": "Chart limit", "minimum": 1, "maximum": 200, "type": "integer", "description": "Max chart positions (Apple up to 200).", "default": 100 }, "enrichFromHtml": { "title": "Apple: enrich from HTML", "type": "boolean", "description": "Fetch apps.apple.com for subtitle, privacy labels, IAP, rating histogram.", "default": false }, "enrichChartDetails": { "title": "Apple: enrich chart rows", "type": "boolean", "description": "Re-lookup each Apple chart app for full metadata.", "default": false }, "includeSimilarApps": { "title": "Play: similar apps", "type": "boolean", "description": "In app_details, emit similar_app rows.", "default": false }, "similarLimit": { "title": "Play: similar apps limit", "minimum": 1, "maximum": 100, "type": "integer", "description": "Max similar_app rows per source app.", "default": 40 }, "includePermissions": { "title": "Play: permissions", "type": "boolean", "description": "In app_details, emit permission rows.", "default": false }, "includeDataSafety": { "title": "Play: data safety", "type": "boolean", "description": "In app_details, emit data_safety row.", "default": false }, "enrichListings": { "title": "Play: enrich search/chart listings", "type": "boolean", "description": "Fetch full details for each Play search/chart hit.", "default": false }, "enrichDeveloperApps": { "title": "Play: enrich developer apps", "type": "boolean", "description": "Fetch full details for each Play developer listing.", "default": false }, "maxSearchPages": { "title": "Play: max search pages", "minimum": 1, "maximum": 10, "type": "integer", "description": "Paginate Play search (1–10).", "default": 3 }, "maxReviewsPerApp": { "title": "Max reviews per app", "minimum": 1, "maximum": 20000, "type": "integer", "description": "Per app (and per Apple country). Apple RSS hard-caps ~500.", "default": 100 }, "appleReviewSort": { "title": "Apple review sort", "enum": [ "mostRecent", "mostHelpful" ], "type": "string", "description": "App Store RSS review sort order.", "default": "mostRecent" }, "googleReviewSort": { "title": "Google review sort", "enum": [ "NEWEST", "HELPFULNESS", "RATING" ], "type": "string", "description": "Google Play review sort order.", "default": "NEWEST" }, "reviewScoreFilter": { "title": "Play: review score filter", "minimum": 0, "maximum": 5, "type": "integer", "description": "0 = all; 1–5 = only that star rating.", "default": 0 }, "reviewAfterDate": { "title": "Play: reviews after date", "type": "string", "description": "ISO date/time. Skip older reviews when sorting NEWEST.", "default": "" }, "rankHistoryLimit": { "title": "Apple rank history limit", "minimum": 1, "maximum": 100, "type": "integer", "description": "Past keyword-rank snapshots to keep per app×keyword×country.", "default": 30 }, "emitRankChanges": { "title": "Emit rank change events", "type": "boolean", "description": "Apple keyword_ranks: also push RANK_CHANGE monitor events.", "default": true }, "monitorStoreName": { "title": "Monitor / rank KV store name", "type": "string", "description": "Named Key-Value Store prefix. Apple and Google use separate keys inside.", "default": "app-stores-aso-state" }, "monitorBaselineOnly": { "title": "Monitor baseline only", "type": "boolean", "description": "Seed fingerprints / ranks without emitting deltas.", "default": false }, "resetMonitorState": { "title": "Reset monitor state", "type": "boolean", "description": "Clear stored fingerprints / rank history before this run.", "default": false }, "monitorFetchReviews": { "title": "Play monitor: fetch new reviews", "type": "boolean", "description": "In monitor mode on Google, also pull newest reviews.", "default": true }, "webhookUrl": { "title": "Play monitor webhook URL", "type": "string", "description": "Optional Slack/Discord/custom HTTPS webhook for Play monitor events.", "default": "" }, "notifyOnNewVersion": { "title": "Webhook: new version", "type": "boolean", "description": "Fire Play webhook when version or update timestamp changes.", "default": true }, "notifyOnRatingDrop": { "title": "Webhook: rating drop", "type": "boolean", "description": "Fire Play webhook when score drops by ratingDropThreshold or more.", "default": true }, "notifyOnPriceChange": { "title": "Webhook: price change", "type": "boolean", "description": "Fire Play webhook when price or currency changes.", "default": true }, "notifyOnNegativeReviews": { "title": "Webhook: negative reviews", "type": "boolean", "description": "Fire Play webhook for new reviews with score <= 2.", "default": true }, "notifyOnListingChange": { "title": "Webhook: listing change", "type": "boolean", "description": "Fire Play webhook when title, summary, or icon changes.", "default": true }, "ratingDropThreshold": { "title": "Rating drop threshold", "minimum": 0, "type": "number", "description": "Minimum Play score drop to emit rating_drop.", "default": 0.2 }, "maxItems": { "title": "Max items", "minimum": 0, "type": "integer", "description": "Hard cap on dataset rows for the whole run (0 = unlimited). When both stores run and balanceStoreLimits is on, this total is split evenly (e.g. 100 → 50 Apple + 50 Google).", "default": 0 }, "maxItemsPerStore": { "title": "Max items per store", "minimum": 0, "type": "integer", "description": "Optional per-store cap. When set, each selected store may push up to this many rows (global maxItems still applies). 0 = auto-split maxItems across stores.", "default": 0 }, "balanceStoreLimits": { "title": "Balance store limits", "type": "boolean", "description": "When both Apple and Google run and maxItemsPerStore is 0, split maxItems evenly so one store cannot consume the whole quota.", "default": true }, "concurrency": { "title": "Concurrency", "minimum": 1, "maximum": 32, "type": "integer", "description": "Parallel workers per store pipeline.", "default": 6 }, "maxRequestsPerSecond": { "title": "Apple max RPS", "minimum": 0.5, "maximum": 30, "type": "number", "description": "Client-side rate limit for iTunes / RSS calls.", "default": 8 }, "runStoresInParallel": { "title": "Run stores in parallel", "type": "boolean", "description": "When both stores selected, scrape Apple and Google concurrently.", "default": true }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy recommended for Google Play (defaults to RESIDENTIAL when enabled). Usually optional for Apple iTunes JSON.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } }, "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 } } } } } } } } } }