{ "openapi": "3.0.1", "info": { "title": "Kolesa.kz Scraper — Kazakhstan Car Listings", "description": "Car ads from kolesa.kz, the largest auto classifieds in Kazakhstan: filter by make/model, city or region, year, price, mileage, body, fuel, gearbox, drive, color, customs status, dealers/private, credit.", "version": "0.1", "x-build-id": "q6ThlBIUgCKRmnEj1" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/yadroo~kolesa-kz/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-yadroo-kolesa-kz", "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/yadroo~kolesa-kz/runs": { "post": { "operationId": "runs-sync-yadroo-kolesa-kz", "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/yadroo~kolesa-kz/run-sync": { "post": { "operationId": "run-sync-yadroo-kolesa-kz", "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": { "make": { "title": "Make (brand slug)", "type": "string", "description": "Brand slug as in kolesa.kz URLs: toyota, hyundai, kia, lexus, bmw, mercedes-benz, volkswagen, chevrolet, nissan, mitsubishi, honda, mazda, subaru, audi, land-rover, vaz (Lada), gaz, uaz, chery, haval, geely, byd, changan, exeed, jetour, jac… \"Mercedes-Benz\", \"Land Rover\" or \"Тойота\" are slugified automatically; typos are auto-corrected against kolesa.kz's own make list (\"Toyta\" → toyota) and shown in the log. Empty = all makes." }, "model": { "title": "Model slug", "type": "string", "description": "Requires make; empty = all models of the make. Model slug as in kolesa.kz URLs: camry, land-cruiser-prado, x5, elantra, sonata, k5, rx, tucson… kolesa.kz searches models only inside a brand, so a model without a make fails with a clear message instead of returning every car. Typos are auto-corrected against the make's model list on kolesa.kz (camri → camry, Королла → corolla) and reported in the log, status and SUMMARY; no close match fails the run with the list of valid slugs." }, "generation": { "title": "Generation slug", "type": "string", "description": "Generation code or name as shown on the ad page, e.g. XV70, NX4, VIII. kolesa.kz has no URL filter for generations, so this works only with detail=true: each ad page is opened and kept only if its «Поколение» text contains this value. Narrow with yearFrom/yearTo first." }, "city": { "title": "City or region slug", "type": "string", "description": "Empty = all Kazakhstan (no default; the form pre-fills almaty). City, region or country slug as in kolesa.kz URLs. Cities: almaty, astana, shymkent, karaganda, aktobe, aktau, atyrau, kostanai, pavlodar, semei, taraz, uralsk, ust-kamenogorsk, kokshetau… Whole region: region-almatinskaya-oblast, region-akmolinskaya-oblast… Cars listed abroad: rossiya, kyrgyzstan, ujnaya-koreya… Russian names accepted. Full tables in README → Reference." }, "yearFrom": { "title": "Year from", "minimum": 1950, "maximum": 2100, "type": "integer", "description": "Model year from." }, "yearTo": { "title": "Year to", "minimum": 1950, "maximum": 2100, "type": "integer", "description": "Model year to." }, "priceFrom": { "title": "Price from, ₸", "minimum": 0, "type": "integer", "description": "Minimum price in tenge." }, "priceTo": { "title": "Price to, ₸", "minimum": 0, "type": "integer", "description": "Maximum price in tenge." }, "monthlyPaymentFrom": { "title": "Monthly credit payment from, ₸", "minimum": 0, "type": "integer", "description": "Minimum monthly loan payment shown by kolesa.kz financing (month-pay[from]). Useful together with inCredit." }, "monthlyPaymentTo": { "title": "Monthly credit payment to, ₸", "minimum": 0, "type": "integer", "description": "Maximum monthly loan payment (month-pay[to]) — e.g. 'cars I can buy for ≤150 000 ₸/month'." }, "mileageTo": { "title": "Mileage to, km", "minimum": 0, "type": "integer", "description": "Maximum odometer reading in km (kolesa.kz has no lower bound filter)." }, "volumeFrom": { "title": "Engine volume from, L", "minimum": 0, "type": "number", "description": "Engine displacement from, litres (decimals allowed, e.g. 1.6 or 2.5)." }, "volumeTo": { "title": "Engine volume to, L", "minimum": 0, "type": "number", "description": "Engine displacement to, litres." }, "body": { "title": "Body type", "type": "array", "description": "Body types to include. Several values = OR.", "items": { "type": "string", "enum": [ "sedan", "wagon", "hatchback", "limousine", "coupe", "roadster", "cabriolet", "suv", "crossover", "microvan", "minivan", "minibus", "van", "pickup", "targa", "fastback", "liftback", "hardtop" ], "enumTitles": [ "Sedan", "Station wagon", "Hatchback", "Limousine", "Coupe", "Roadster", "Cabriolet", "SUV (внедорожник)", "Crossover", "Microvan", "Minivan", "Minibus", "Van (фургон)", "Pickup", "Targa", "Fastback", "Liftback", "Hardtop" ] } }, "fuel": { "title": "Fuel", "type": "array", "description": "Engine/fuel type. Several values = OR.", "items": { "type": "string", "enum": [ "petrol", "diesel", "lpgPetrol", "lpg", "hybrid", "electric" ], "enumTitles": [ "Petrol", "Diesel", "LPG + petrol", "LPG", "Hybrid", "Electric" ] } }, "transmission": { "title": "Transmission", "type": "array", "description": "Gearbox. automaticAny = any automatic (automatic, tiptronic, CVT, robot). Several values = OR.", "items": { "type": "string", "enum": [ "manual", "automaticAny", "automatic", "tiptronic", "cvt", "robot" ], "enumTitles": [ "Manual", "Automatic (any)", "Automatic (classic)", "Tiptronic", "CVT", "Robotized" ] } }, "steeringWheel": { "title": "Steering wheel", "enum": [ "left", "right" ], "type": "string", "description": "Left- or right-hand drive. Leave unset for any." }, "drive": { "title": "Drive", "type": "array", "description": "Drivetrain. Several values = OR.", "items": { "type": "string", "enum": [ "front", "all", "rear" ], "enumTitles": [ "Front-wheel", "All-wheel", "Rear-wheel" ] } }, "color": { "title": "Color", "type": "array", "description": "Body color. Several values = OR.", "items": { "type": "string", "enum": [ "white", "black", "grey", "silver", "blue", "lightBlue", "red", "green", "brown", "beige", "gold", "yellow", "orange", "burgundy", "cherry", "bronze", "purple", "lilac", "pink", "turquoise", "chameleon" ], "enumTitles": [ "White", "Black", "Grey", "Silver", "Blue", "Light blue", "Red", "Green", "Brown", "Beige", "Gold", "Yellow", "Orange", "Burgundy", "Cherry", "Bronze", "Purple", "Lilac", "Pink", "Turquoise", "Chameleon" ] } }, "metallic": { "title": "Metallic paint only", "type": "boolean", "description": "Only metallic colors.", "default": false }, "condition": { "title": "Condition", "enum": [ "new", "used" ], "type": "string", "description": "new = brand-new cars (dealer stock), used = with mileage. Leave unset for any. Sent as kolesa's own URL path segment, so all other filters keep working." }, "availability": { "title": "Availability", "enum": [ "inStock", "onOrder" ], "type": "string", "description": "In stock vs. on order (mostly for new cars). Leave unset for any." }, "bodyGroup": { "title": "Body group", "enum": [ "cars", "suvPickup", "minivanBus" ], "type": "string", "description": "Coarse vehicle class as on the kolesa.kz top tabs. Leave unset for any." }, "markCountry": { "title": "Brand origin country", "enum": [ "europe", "uk", "germany", "italy", "spain", "france", "czech", "sweden", "china", "korea", "russia", "usa", "japan", "other" ], "type": "string", "description": "Country of origin of the brand (kolesa.kz 'Страна происхождения марки'). Leave unset for any." }, "customsCleared": { "title": "Customs cleared in KZ only", "type": "boolean", "description": "Only cars cleared through Kazakhstan customs (растаможен).", "default": false }, "withPhoto": { "title": "With photos only", "type": "boolean", "description": "Skip listings without photos.", "default": false }, "carHistory": { "title": "With car history report", "type": "boolean", "description": "Only listings with the kolesa.kz 'История авто' report.", "default": false }, "damaged": { "title": "Damaged / not running only", "type": "boolean", "description": "Only cars flagged 'Аварийная/Не на ходу' (salvage buyers).", "default": false }, "dealersOnly": { "title": "Dealers only", "type": "boolean", "description": "Only listings from dealers.", "default": false }, "inCredit": { "title": "Available on credit", "type": "boolean", "description": "Only cars available with kolesa.kz financing.", "default": false }, "keywords": { "title": "Keywords", "type": "string", "description": "Free-text search inside listing descriptions (kolesa.kz `_txt_`), e.g. \"один хозяин\" or \"обмен\"." }, "extraParams": { "title": "Extra raw parameters", "type": "object", "description": "Escape hatch for any kolesa.kz query parameter not listed above, copied from the site URL, e.g. {\"deposit[to]\": 1000000}." }, "sort": { "title": "Sort", "enum": [ "newest", "oldest", "cheapest", "expensive", "yearDesc", "yearThenPrice" ], "type": "string", "description": "Result order as on kolesa.kz.", "default": "newest" }, "sinceHours": { "title": "Only listings from the last N hours", "minimum": 1, "maximum": 8760, "type": "integer", "description": "Keep only listings published within the last N hours (card dates are day-precise; detail=true adds exact publication timestamps). With sort=newest pagination stops at the first fully-old page — ideal for monitoring." }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Stop after this many listings (~20 per page). A run with a spending limit collects no more than the limit pays for.", "default": 40 }, "maxPages": { "title": "Max pages", "minimum": 1, "maximum": 300, "type": "integer", "description": "Safety cap on search pages.", "default": 50 }, "detail": { "title": "Open each listing page (full details)", "type": "boolean", "description": "Fetch every listing page to add: generation, drive, steering wheel, color, customs status, full options list, seller description, exact publication/update timestamps, kolesa.kz average market price for the model (avgPrice) and the % difference (priceVsAvgPct), seller type (private/dealer), credit availability. +1 request per listing.", "default": false }, "detailDelaySecs": { "title": "Delay between listing pages, s (detail mode)", "minimum": 1, "maximum": 60, "type": "number", "description": "Minimum seconds between two listing pages on one IP in detail mode (1–60). Empty = 1.5 s. kolesa.kz cuts off an IP that sends too many requests in a short time (for 15+ minutes), so the Actor paces every request anyway: a short burst, then about 4 a minute per IP. Set 20–30 only if your detail runs still report a block." }, "includeViews": { "title": "Include view counts", "type": "boolean", "description": "Attach the site's view counter to each listing (1 batch request per search page, or per 25 listings in detail mode).", "default": true }, "includeVip": { "title": "Include VIP block listings", "type": "boolean", "description": "Include ads from kolesa's paid VIP carousel above the results. The carousel ignores year, price and most filters, so every VIP card is checked against your filters and dropped when it does not match or cannot be verified from the card. Kept VIP ads are marked isVip / fromVipBlock and ignore the sort order.", "default": true }, "dedupe": { "title": "Deduplicate by listing id", "type": "boolean", "description": "Drop repeated ids across pages and VIP/TOP blocks.", "default": true }, "proxyConfiguration": { "title": "Proxy (turns on fast mode)", "type": "object", "description": "Off (default): the normal run on one IP — a short burst, then about 4 requests a minute (kolesa.kz cuts off a faster IP for 15+ minutes). On: fast mode — up to 8 IPs at once, each at that same pace; with Apify Proxy each listing costs $0.004 instead of $0.003 (one price, not both). Pick group RESIDENTIAL: a small datacenter pool has fewer distinct IPs, and an IP already in use is never used twice. Own proxy URLs (one per IP, up to 10 at once) keep the normal price.", "default": { "useApifyProxy": false } } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }