Kazakhstan's biggest car marketplace, as one JSON API

Tenge (KZT), whole units, with no sub-unit — and nothing else: every price on every page we sampled was in tenge, and there is no second currency on this site. Each row returns price as an integer plus price_display, the exact string Kolesa prints on its own card ("350 000 ₸", "71 500 000 ₸"), so you can check our number against the source's own rendering rather than trusting us. Across 12 cohorts, the integer and the printed string agreed 12 of 12, with zero mismatches. We do not convert anything to dollars: a converted price is our arithmetic, not the seller's asking price.

Kolesa's own average asking price for that brand and model, which it prints next to its own listings. It is the site's figure, not our calculation, and we pass it through unchanged — so a 350,000 ₸ Toyota Corsa comes back with market_avg_price 429,000 and a 1,150,000 ₸ Lada Priora with 1,493,000. It is not on every row: Kolesa publishes it for models it has enough data on, and where it does not, the field is null rather than a guess.

Every search row and every detail record carries seller_kind, which is either private or business, and we did not infer it from the ad's wording. Kolesa's own dealer filter narrowed the 161,697-ad board to 10,060, and on that filtered page all 20 rows came back business while all 20 rows of the unfiltered control came back private — a clean 40-row split. Set dealers_only to get only businesses; to get only private owners, filter the rows on seller_kind, because Kolesa's own who parameter returns an empty page for every value we tried and we will not ship a handle that does nothing.

What the ad page itself shows, unmodified. For a dealer that is the business name, the "official dealer" badge, the street address, how long they have been on Kolesa and how many ads they have live — on one sampled dealer: Porsche Centre Astana, official dealer, Астана, Проспект Туран 74/1, 2 years on Kolesa.kz, 72 ads. For a private owner it is the seller id, the kind, and the phone prefix the page prints (for example "+7 775") with how many numbers are on file. 🔴 A private owner's display name is NOT published on the ad page at all — Kolesa only reveals it together with the phone number — so seller.name is null there and seller.name_published tells you so. We would rather say that than show you an empty string and let you guess.

No. Kolesa keeps the number behind a separate request on its own site, and this API never makes it and never returns it. What you do get is what the ad page itself prints: the dialling prefix (for example "+7 775"), how many numbers the seller has on file, and whether the seller has chosen to hide them.

Every filter we expose was measured against the same-run unfiltered control of 161,697 ads, and only the ones that moved the total are offered — 22 for 22. Some examples: Toyota 29,943, Toyota Camry 10,454, Almaty 42,852, a 2–3 million tenge band 19,497, under 50,000 km 19,406, crossover 30,864, manual 53,372, electric 1,254, white 31,047, right-hand drive 9,578, all-wheel drive 48,905, brand new 4,667, dealers 10,060, damaged 3,230. Two things the site accepts and then ignores are deliberately not exposed: an unknown parameter name (we passed a nonsense key and got the identical 161,697 rows back) and an unknown sort value (the row order did not budge). So an unknown enum or sort gets INVALID_PARAM from us instead of a convincing wrong answer from the site.

Twenty thousand per query, and we say so in every response. Kolesa stops at page 1,000 — its own page selector reads "1 из 1000", and pages 1,001, 1,500 and 4,000 all return exactly the rows page 1,000 returns. At 20 rows a page that is 20,000 rows, so the full 161,697-ad board cannot be walked in one query. Every search response carries total_results (Kolesa's own count) and reachable_rows (the smaller, honest number), plus page_at_ceiling so a crawler knows to stop. The fix is to split the query: by brand, by city, by price band or by year. Every slice at or below 20,000 ads — Toyota Camry, Astana, a 2–3 million tenge band, electric, new, dealers, diesel, right-hand drive — is reachable to its last row.

Twenty, and it is fixed — there is no page-size parameter on this site and we do not pretend otherwise. We measured 20 rows on pages 1, 2, 3, 7, 50, 300 and 1,000, and the response reports page_size from what actually came back rather than from a constant. Each page also carries up to three paid "VIP" placement cards that Kolesa itself does not count as results; those are excluded and the number removed is reported as promoted_tiles_excluded, so your row count is never quietly different.

Because the card did not print one. Kolesa's search cards show a chip row — year, condition and body, engine size, fuel, steering side, gearbox, mileage, colour, then options — and not every ad fills every chip: a 1995 Toyota Corsa came back with 420,000 km and no gaps, while a 2012 Lada Priora on the same page printed no mileage and no steering side at all. We return null for what the source did not publish instead of a zero, and the raw chip list is in spec_line on every row so you can see exactly what the card said. If you need mileage guaranteed, call listing: the detail page's own parameter table carries it where the seller entered it.

Only a maximum. Kolesa publishes an upper mileage bound in its own form and no lower one, so mileage_max exists (measured: 161,697 to 19,406 at 50,000 km) and mileage_min does not. We would rather leave it out than ship a parameter the site throws away — on this site an unknown parameter is accepted silently and changes nothing, which is exactly how a useless filter looks like a working one.

Yes — brand and model are Kolesa's own URL slugs, so toyota, bmw, mercedes-benz, hyundai, lada, camry, land-cruiser and x5 are what you pass, and every search row returns its own brand and model so the spelling never has to be guessed twice. Two honest limits: model only works together with brand (Kolesa answers a bare model with a 404, and we return MISSING_PARAM with that reason rather than a mysterious empty page), and an unknown brand slug comes back as NOT_FOUND because that is literally what the site answers.

No, and we block it rather than answer the wrong question. City goes into Kolesa's URL path and region into its query string, and when both are present the region silently wins: /cars/almaty/ with the Almaty-region filter added returned 44,537 ads — the region's number — not Almaty city's 42,852. So the pair returns INVALID_PARAM with that measurement in the message. Pass one: city for a single city (almaty 42,852, astana 20,391, shymkent 13,725), region for a whole oblast.

The complete seller description instead of the truncated card text — 356 and 731 characters on the two ads we sampled, with the site's <br> tags and HTML entities already cleaned out — plus every photo at full size (7 and 34 on those two ads, matching Kolesa's own photo count exactly both times), the entire parameter table the ad page prints as label/value rows (10 and 9 rows on those two: city, generation, body, engine, mileage, gearbox, drivetrain, steering, colour, customs status), the option list, and the seller block described above. Everything in the search row is in there too, and an advert id taken from search resolved to the same record every time we checked.

You get NOT_FOUND with a message saying the advert is removed or never existed, never a blank success you have to interpret — Kolesa answers a dead id with a real 404 and we pass that through as the answer it is. A search that genuinely matches nothing is a different thing and treated as one: ok with zero rows, total_results 0, and an empty_reason saying the site returned its own "nothing found" page. We measured both, on two separate runs.