# Kaspi.kz Price & Rank Monitor (multi-city) (`isolovyev/kaspi-price-monitor`) Actor 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. - **URL**: https://apify.com/isolovyev/kaspi-price-monitor.md - **Developed by:** [Ivan Solovyev](https://apify.com/isolovyev) (community) - **Categories:** E-commerce, Automation, SEO tools - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Kaspi.kz Price Scraper & Monitor 🇰🇿 Scrape and **monitor** product prices on **Kaspi.kz**, Kazakhstan's #1 marketplace (Kaspi Магазин). Get prices in KZT, Kaspi-bonus price, rating, review counts, stock, and installment plans, across **multiple Kazakh cities in a single run**. Unlike simple one-shot scrapers, this Actor has a **monitor mode** that tracks price changes between runs and a **reviews-velocity** signal for demand. Built on Kaspi's own JSON API (no browser), so it is fast, cheap, and reliable. ### Why this Actor - **Multi-city in one run** - Kaspi prices and stock vary by city; scrape Almaty, Astana, Shymkent and more at once. - **Monitor mode** - compare each run to the previous one and get `price_up` / `price_down` / `new` / `removed` with exact `priceChangePct`. Perfect for repricing and MAP monitoring. - **Reviews-velocity** - `reviewsDelta` shows how fast a product gains reviews between runs: a proxy for sales velocity / demand. - **Webhook alerts** - POST changes to your own endpoint (n8n, Make, Zapier) for Telegram/Slack alerts. - **Degradation alerts** - flags cities that returned zero results while others worked. - **No browser** - direct JSON API keeps runs fast and inexpensive. ### Use cases - **Repricing / buy-box** for Kaspi Магазин sellers - track competitors' prices per city. - **Brand MAP monitoring** - detect sellers breaking minimum advertised price. - **Market research** - category price levels, ratings, demand (reviews) across cities. - **Deal / price-drop alerts** - monitor a basket of products and get notified on drops. ### Input | Field | Description | |---|---| | `mode` | `search` (current listings) or `monitor` (price changes vs last run) | | `searchQueries` | Keywords, RU or KZ (e.g. `iphone`, `холодильник`) | | `cities` | Kaspi city IDs - `750000000` Almaty, `710000000` Astana, `591010000` Shymkent, `351010000` Karaganda, `271010000` Aktobe, `551010000` Pavlodar | | `maxPagesPerQuery` | 12 products per page | | `maxItemsPerQuery` | Optional cap | | `alertOnly` | Monitor: emit only changed products | | `priceChangeThresholdPct` | Monitor: minimum % change to report | | `notifyWebhookUrl` | Monitor: POST run summary for alerts | | `proxyConfiguration` | Optional (the API works without a proxy) | ### Output (per product) `platform, query, id, title, brand, price (KZT), bonusPrice, rating, reviews, stock, monthlyInstallment, category, city, cityName, url, currency, scrapedAt` In **monitor mode** each item also has: `changeType, previousPrice, priceChangePct, reviewsDelta`. ### Monitor setup Run in `monitor` mode on an **Apify Schedule** (e.g. daily). The Actor stores state between runs, so each run reports what changed since the last one. Set `notifyWebhookUrl` to push alerts into your own workflow. ### Quick start **Search mode** - current listings across cities, with share-of-shelf: ```json { "mode": "search", "searchQueries": ["iphone 15", "холодильник"], "cities": ["750000000", "710000000"], "maxPagesPerQuery": 5, "shareOfShelf": true, "shareTopN": 20, "ownBrand": "Apple" } ```` **Monitor mode** - price/rank deltas on a schedule, alert only on changes: ```json { "mode": "monitor", "searchQueries": ["iphone 15"], "cities": ["750000000"], "alertOnly": true, "priceChangeThresholdPct": 3, "rankDropThreshold": 3, "notifyWebhookUrl": "https://example.com/hooks/kaspi-alerts" } ``` Set a schedule under **Schedules** in the Apify Console to run `monitor` mode periodically. State carries over between runs via the Key-Value Store. ### Pricing Direct JSON API, no browser - this keeps the Actor cheap: roughly **$1.5 per 1000 product cards**, plus Apify platform usage (compute + proxy, if you enable one). Use `alertOnly=true` in monitor mode to write (and pay for) only changed cards; the underlying scan is still billed as platform usage. ### Notes - Prices are in **KZT** and reflect the selected `city`. - The API returns 12 products per page; use `maxPagesPerQuery` to control depth and cost. ### KZ / Қазақша **Kaspi.kz - Қазақстанның №1 маркетплейсіндегі тауарлардың бағасын, рейтингін және іздеудегі орнын (рангін) қалалар бойынша жинау мен бақылау. Тікелей JSON-API, браузерсіз: арзан әрі сенімді.** - **Бір жүгірісте бірнеше қала** - Kaspi-дегі баға мен қолжетімділік қалаға қарай өзгереді; Алматы, Астана, Шымкент және басқаларын бір мезгілде жинаңыз. - **Мониторинг режимі** - әр жүгіріс алдыңғысымен салыстырылып, `price_up` / `price_down` / `new` / `removed` және нақты `priceChangePct` беріледі. Repricing пен MAP-бақылау үшін ыңғайлы. - **Reviews-velocity** - `reviewsDelta` пікірлердің қаншалықты тез жиналып жатқанын көрсетеді: сұраныс пен сату қарқынының белгісі. - **Share-of-shelf** - сұраныс бойынша топ-N ішіндегі бренд пен сатушының көріну үлесі және өз брендіңіздің орындары. - **Webhook хабарламалары** - өзгерістерді өз қызметіңізге (Telegram, n8n, Make) жіберіңіз. Баға теңгемен (KZT) көрсетіледі және таңдалған қалаға сәйкес келеді. API бір бетте 12 тауардан береді; тереңдік пен шығынды `maxPagesPerQuery` арқылы реттеңіз. Актор Apify residential (KZ) прокси арқылы жұмыс істейді, трафикті іске қосушы төлейді. ### RU / На русском **Мониторинг цен, рейтинга и позиции (ранга) товаров на Kaspi.kz - маркетплейсе №1 Казахстана - по городам. Прямой JSON-API, без браузера: дёшево и надёжно.** - **Много городов за один прогон** - цена, бонус-цена, рейтинг, отзывы и сток зависят от города; Алматы, Астана, Шымкент и другие - разом. - **Режим monitor** - сравнивает текущий прогон с предыдущим и отдаёт `price_up` / `price_down` / `new` / `removed` с точным `priceChangePct`, плюс `reviewsDelta` (скорость набора отзывов - прокси спроса) и композитные алерты `changeReasons` вроде `rank_drop` (конкурент обошёл вас в выдаче) или `undercut`. - **Share-of-shelf** - доля видимости бренда/продавца в топ-N выдачи по запросу и городу, включая позицию собственного бренда (`ownBrand`), отдельным датасетом. - **Вебхук** - POST сводки изменений на свой эндпоинт (n8n/Make/Zapier → Telegram/Slack). - **Без браузера** - Actor работает по собственному JSON-API Kaspi, поэтому быстрый и дешёвый. **Честные ограничения:** только Kaspi.kz/Казахстан - другие площадки не поддерживаются; API отдаёт данные без прокси, но для стабильного казахстанского IP на Apify рекомендуется residential-прокси со страной KZ (поле `proxyConfiguration`); 12 товаров на странице API, глубина и стоимость регулируются `maxPagesPerQuery`. Тариф - по модели Pay-per-event, ориентировочно **~$1.5 за 1000 карточек** плюс platform usage (compute/proxy) по правилам аккаунта Apify - прайс-мониторинг тут узкая ниша, поэтому цена держится низкой. # Actor input Schema ## `mode` (type: `string`): search = collect current listings. monitor = compare prices vs the previous run (needs a schedule) and emit price changes + review-velocity, with optional webhook alerts. ## `searchQueries` (type: `array`): Keywords to search on Kaspi.kz, e.g. 'iphone', 'холодильник', 'наушники'. Russian or Kazakh. ## `cities` (type: `array`): 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. ## `maxPagesPerQuery` (type: `integer`): 12 products per page. Higher = more products, more cost. ## `maxItemsPerQuery` (type: `integer`): Optional hard cap on products kept per query/city. ## `alertOnly` (type: `boolean`): Monitor mode only: emit just the products whose price changed (or new/removed) beyond the threshold, instead of the full set. ## `priceChangeThresholdPct` (type: `integer`): Monitor + alertOnly: only report price changes of at least this percent. ## `rankDropThreshold` (type: `integer`): 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). ## `notifyWebhookUrl` (type: `string`): 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` (type: `boolean`): 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. ## `shareTopN` (type: `integer`): Search + shareOfShelf: how many top search-rank positions to compute brand/seller share over. ## `ownBrand` (type: `string`): Search + shareOfShelf: your brand name (matched case-insensitively). If set, the share-of-shelf summary includes its position/share within the top-N. ## `proxyConfiguration` (type: `object`): Optional. The Kaspi JSON API works without a proxy, but you can enable Apify Proxy for scale or specific geo. ## Actor input object example ```json { "mode": "search", "searchQueries": [ "iphone" ], "cities": [ "750000000" ], "maxPagesPerQuery": 10, "alertOnly": false, "priceChangeThresholdPct": 0, "rankDropThreshold": 3, "shareOfShelf": false, "shareTopN": 20, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "KZ" } } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "searchQueries": [ "iphone" ], "cities": [ "750000000" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "KZ" } }; // Run the Actor and wait for it to finish const run = await client.actor("isolovyev/kaspi-price-monitor").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "searchQueries": ["iphone"], "cities": ["750000000"], "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "KZ", }, } # Run the Actor and wait for it to finish run = client.actor("isolovyev/kaspi-price-monitor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "searchQueries": [ "iphone" ], "cities": [ "750000000" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "KZ" } }' | apify call isolovyev/kaspi-price-monitor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=isolovyev/kaspi-price-monitor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "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": "ZjwQAagQueA5DA1AS" }, "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 } } } } } } } } } } ```