{ "openapi": "3.0.1", "info": { "title": "Kaspi.kz Price & Rank Monitor (multi-city)", "description": "Scrape and monitor Kaspi.kz (Kazakhstan's #1 marketplace): price (KZT), bonus price, search rank, rating, reviews, stock. Multi-city, monitor mode tracks price and rank changes between runs plus reviews-velocity, with webhook alerts. Direct JSON API, no browser.", "version": "0.1", "x-build-id": "S76PjvLQNQxmymGvQ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/isolovyev~kaspi-price-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-isolovyev-kaspi-price-monitor", "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/isolovyev~kaspi-price-monitor/runs": { "post": { "operationId": "runs-sync-isolovyev-kaspi-price-monitor", "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/isolovyev~kaspi-price-monitor/run-sync": { "post": { "operationId": "run-sync-isolovyev-kaspi-price-monitor", "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": [ "searchQueries" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "monitor" ], "type": "string", "description": "search = collect current listings. monitor = compare prices vs the previous run (needs a schedule) and emit price changes + review-velocity, with optional webhook alerts.", "default": "search" }, "searchQueries": { "title": "Search queries", "type": "array", "description": "Keywords to search on Kaspi.kz, e.g. 'iphone', 'холодильник', 'наушники'. Russian or Kazakh.", "items": { "type": "string" } }, "cities": { "title": "Cities", "type": "array", "description": "Kaspi city IDs. Prices, stock and delivery vary by city. 750000000 Almaty, 710000000 Astana, 591010000 Shymkent, 351010000 Karaganda, 271010000 Aktobe, 551010000 Pavlodar. You can scrape several cities in one run.", "default": [ "750000000" ], "items": { "type": "string" } }, "maxPagesPerQuery": { "title": "Max pages per query (per city)", "minimum": 1, "maximum": 25, "type": "integer", "description": "12 products per page. Higher = more products, more cost.", "default": 10 }, "maxItemsPerQuery": { "title": "Max items per query (per city)", "type": "integer", "description": "Optional hard cap on products kept per query/city." }, "alertOnly": { "title": "Monitor: alert only on changes", "type": "boolean", "description": "Monitor mode only: emit just the products whose price changed (or new/removed) beyond the threshold, instead of the full set.", "default": false }, "priceChangeThresholdPct": { "title": "Monitor: price-change threshold (%)", "type": "integer", "description": "Monitor + alertOnly: only report price changes of at least this percent.", "default": 0 }, "rankDropThreshold": { "title": "Monitor: rank-drop threshold (positions)", "minimum": 1, "type": "integer", "description": "Monitor mode: flag changeReasons=['rank_drop'] when a SKU's search rank worsens by at least this many positions vs the previous run (competitors overtook it).", "default": 3 }, "notifyWebhookUrl": { "title": "Monitor: notify webhook URL", "type": "string", "description": "Monitor mode: POST the run summary (counts, per-city, degraded, changes) to this URL — wire it to n8n/Zapier/Make for Telegram/Slack alerts." }, "shareOfShelf": { "title": "Search: compute share-of-shelf", "type": "boolean", "description": "Search mode: compute one competitive-visibility summary per (query, city) — brand and seller share among the top-N search results. Written to a separate named dataset ('kaspi-share-of-shelf'), not mixed into the product-card dataset.", "default": false }, "shareTopN": { "title": "Search: share-of-shelf top-N", "minimum": 1, "maximum": 100, "type": "integer", "description": "Search + shareOfShelf: how many top search-rank positions to compute brand/seller share over.", "default": 20 }, "ownBrand": { "title": "Search: own brand (for share-of-shelf)", "type": "string", "description": "Search + shareOfShelf: your brand name (matched case-insensitively). If set, the share-of-shelf summary includes its position/share within the top-N." }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optional. The Kaspi JSON API works without a proxy, but you can enable Apify Proxy for scale or specific geo.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "KZ" } } } }, "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 } } } } } } } } } }