{ "openapi": "3.0.1", "info": { "title": "App Store Keyword Rank Tracker — iOS & Google Play", "description": "Where any app ranks for any keyword on the App Store and Google Play, in 54 storefronts. Reads Apple's own store search — not the iTunes Search API. Rank, rank change vs your last run, competitors above you, autocomplete suggestions and a free competition readout, in one dataset. No API key.", "version": "0.1", "x-build-id": "y8cDPhFKcVelOffAB" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/insight.solutions~app-store-keyword-rank-tracker/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-insight.solutions-app-store-keyword-rank-tracker", "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/insight.solutions~app-store-keyword-rank-tracker/runs": { "post": { "operationId": "runs-sync-insight.solutions-app-store-keyword-rank-tracker", "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/insight.solutions~app-store-keyword-rank-tracker/run-sync": { "post": { "operationId": "run-sync-insight.solutions-app-store-keyword-rank-tracker", "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": { "keywords": { "title": "Keywords", "type": "array", "description": "The search terms to read rankings for, e.g. `[\"meditation\", \"sleep tracker\"]`. Each one is looked up in every country and on every platform you selected. Trimmed and de-duplicated case-insensitively; up to 200 per run, 200 characters each.", "default": [], "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "Two-letter ISO 3166-1 country codes. **Apple ranks are available for 54 storefronts** — every one whose id this build has verified against a captured response, including us, gb, de, fr, it, es, jp, kr, cn, in, br, mx, ca, au and 40 more. A country outside that list gets a free `unknown-storefront` row rather than another country's ranks by mistake. Google Play accepts any country code. Up to 25.", "default": [ "us" ], "items": { "type": "string" } }, "platforms": { "title": "Platforms", "type": "array", "description": "Which stores to read. Both produce the same columns, so a run over both is one table.", "items": { "type": "string", "enum": [ "ios", "android" ], "enumTitles": [ "App Store (iOS)", "Google Play (Android)" ] }, "default": [ "ios", "android" ] }, "depth": { "title": "Depth", "minimum": 1, "maximum": 250, "type": "integer", "description": "How many ranked positions to read per keyword. Apple's own search returns the whole list in one request (247 results for `notes` in the US), so depth on iOS costs nothing extra. **Google Play ships one search page — about 30 results in the US, 14 in Germany** — so a higher depth is clamped to what the page gave and the summary row says `depthClamped: true`.", "default": 50 }, "rankSource": { "title": "iOS rank source", "enum": [ "native", "itunes-search-api" ], "type": "string", "description": "`native` is Apple's own store search — the endpoint the App Store app itself queries, and the default. `itunes-search-api` is the public iTunes Search API that most of this category calls \"App Store rankings\"; on the term `notes` in the US the two agree at ρ = 0.880, and 15 of the native top 50 are absent from the iTunes list entirely. Ignored on Android.", "default": "native" }, "apps": { "title": "Your apps (rank check)", "type": "array", "description": "Apps whose position you want for every keyword. Any of: an App Store id (`1110145109`), a bundle id (`com.apple.mobilenotes`), an Android package (`com.google.android.keep`), an `apps.apple.com/…/id…` link or a `play.google.com/store/apps/details?id=…` link. Leave empty to get the ranked list instead. Up to 50.", "default": [], "items": { "type": "string" } }, "language": { "title": "Language", "type": "string", "description": "Two-letter language code. On Apple it is sent as `Accept-Language`; leave it empty and Apple resolves the storefront's own default, which the row reports in `language`. On Google Play it is `hl=`; leave it empty and it is derived from the country (`gl=DE` → `hl=de`)." }, "includeTopApps": { "title": "Include the ranked list", "type": "boolean", "description": "Emit one row per ranked position, not just your own apps' positions. On by default when `apps` is empty; turn it on alongside `apps` to get the competitive field and your positions in one run.", "default": true }, "includeSuggestions": { "title": "Include autocomplete suggestions", "type": "boolean", "description": "Ask each store's own search box what it suggests for each keyword used as a prefix. Apple returns 10 terms per prefix; Google Play returns as many as it has. Charged as `suggestion` rows.", "default": false }, "includeAppDetails": { "title": "Include app details", "type": "boolean", "description": "Fill name, developer, price, rating, genres and links on every ranked row. Free. Apple's own search carries detail for the top 8 results only and rounds ratings to the half star, so every ranked position is filled from a public lookup instead — one request per 100 positions, inside the same row price — which is what keeps the rating column at one precision. Turn it off for fewer requests and the same price.", "default": true }, "includeSummary": { "title": "Include the competition readout", "type": "boolean", "description": "One free `keyword-summary` row per keyword, country and platform: result count, top-10 average rating, free share, genre mix and how many of the top 10 have the keyword in their title. Arithmetic over this run's own rows — no difficulty score, no popularity index.", "default": true }, "monitor": { "title": "Track rank changes between runs", "type": "boolean", "description": "Compare every position against the one this Actor stored on its previous run and emit `rank-change` rows carrying `previousRank`, `rankChange`, `trend`, `bestRank`, `worstRank` and `daysTracked`. State lives in a named key-value store this Actor creates and re-opens. A check that failed is never reported as a rank drop.", "default": false }, "emitUnchanged": { "title": "Emit unchanged positions", "type": "boolean", "description": "Monitor mode only. Leave on for a full picture every run. Turn it off and only positions that moved, entered or dropped out are emitted — the cheap way to run a daily alert.", "default": true }, "firstRunBehavior": { "title": "First run behaviour", "enum": [ "emit-all", "baseline-only" ], "type": "string", "description": "Monitor mode only. `emit-all` returns the first snapshot as ordinary rows, because a first rank reading is the product. `baseline-only` writes the state and bills nothing — which means a run with nothing else in it finishes FAILED and costs you nothing at all.", "default": "emit-all" }, "maxRows": { "title": "Max rows", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Hard ceiling on charged rows. 0 means no ceiling. Free rows — the competition readout and every diagnostic — do not count against it.", "default": 5000 }, "maxRunSecs": { "title": "Max run seconds", "minimum": 30, "maximum": 3600, "type": "integer", "description": "Wall-clock budget for the whole run. Keywords not reached in time get a free `timeout` row and everything already returned is kept.", "default": 240 }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many keyword × country × platform reads run at once. Each slot keeps its own proxy session, so one blocked exit does not burn the others.", "default": 3 }, "residentialFallback": { "title": "Residential fallback for Google Play", "type": "boolean", "description": "When a Google Play page is refused from a datacenter exit even after a new IP is taken, retry that one page through a residential exit. Residential transfer costs 40× more per gigabyte, so it is used for the page that was refused and nothing else. Turn it off to go straight to a free `blocked` row.", "default": true }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify datacenter proxy by default. Apple answers through it, and through no proxy at all; Google Play is read through it in production and falls back to a residential exit for a page that is refused. Set `{\"useApifyProxy\": true, \"apifyProxyGroups\": [\"RESIDENTIAL\"]}` to use residential everywhere — it works, and it costs 40× more per gigabyte on the Play leg.", "default": { "useApifyProxy": true } }, "stateStoreName": { "title": "State store name", "type": "string", "description": "The named key-value store the rank history lives in. Change it to run two independent trackers under one account.", "default": "app-store-keyword-rank-state" } } }, "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 } } } } } } } } } }