Kolesa APIkolesa.kz ↗
Access car listings, spare parts, makes, models, and city data from Kolesa.kz via 7 structured endpoints. Filter by region, body type, drive, and more.
What is the Kolesa API?
The Kolesa.kz API exposes 7 endpoints covering Kazakhstan's largest automotive marketplace — car listings, spare parts, commercial vehicles, motorcycles, and water transport. The search_cars endpoint accepts filters for make, model, body type, drive, color, customs status, and region, returning paginated summaries with price, city, date, and thumbnail. Companion endpoints like get_makes, get_models, and get_cities provide the reference IDs and slugs those filters require.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/a9b1ccd7-3ece-419a-a870-f59a9c013307/get_makes' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace kolesa-kz-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Kolesa.kz SDK — browse makes, search cars, inspect a listing."""
from parse_apis.kolesa_kz_api import Kolesa, VehicleCategory, ListingNotFound
client = Kolesa()
# List popular car makes and print their stats
for make in client.makes.list(limit=5):
print(make.label, make.popular, make.url_alias)
# Get models for the first make (Toyota) via sub-resource navigation
make = client.makes.list(limit=1).first()
if make:
for model in make.models.list(limit=3):
print(model.label, model.url_alias, model.popular)
# Search car listings filtered by make and year range
car = client.carsummaries.search(mark="toyota", year_from="2020", limit=1).first()
if car:
print(car.title, car.price, car.city, car.date)
# Drill into full listing details via summary -> detail navigation
try:
detail = car.details()
print(detail.title, detail.price)
print(detail.seller.name, detail.seller.city)
print(len(detail.photos), "photos")
except ListingNotFound as exc:
print(f"Listing gone: {exc}")
# Search motorcycles using the VehicleCategory enum
for vehicle in client.othervehicles.search(category=VehicleCategory.MOTORCYCLES, limit=3):
print(vehicle.title, vehicle.price, vehicle.city)
# Search spare parts in Russian
for part in client.spareparts.search(query="фара", mark="toyota", limit=3):
print(part.title, part.price, part.url)
print("exercised: makes.list / models.list / carsummaries.search / car.details / othervehicles.search / spareparts.search")
Retrieve the full catalog of car makes (brands) available on Kolesa.kz. Each make includes a numeric ID (used by get_models), a URL-safe slug, popularity count, icon URL, and search synonyms. The list is unpaginated and stable — use it to resolve user-facing brand names to IDs or slugs before calling other endpoints.
No input parameters required.
{
"type": "object",
"fields": {
"items": "array of make objects each containing id, label, urlAlias, icon, synonyms, isPopular, popular count, and brandCountryId"
}
}About the Kolesa API
Reference Data: Makes, Models, and Cities
Before running searches, use get_makes to retrieve the full list of car brands available on Kolesa.kz. Each object in the items array includes an id, label, urlAlias, icon, synonyms, and isPopular flag. Pass the numeric id to get_models to get the model list for that brand — each model carries its own id, urlAlias, bodyGroup, and popularity count. Use get_cities to get Kazakhstan oblasts and international region slugs needed for the region filter across all search endpoints.
Car Listing Search and Detail
search_cars accepts optional parameters for mark, model, body, drive, color, customs, region, and page. Results are paginated; the response includes total_pages and current_page alongside the items array. Each item contains id, title, url, price, city, date, thumbnail, and description_short. To get the full record for any listing, pass its id to get_car_listing, which returns the complete params object (generation, engine, transmission, drive, steering wheel, color, customs status), a photos array, seller info, stats (views and publish date), and the seller's description text.
Spare Parts and Other Vehicle Categories
search_spare_parts searches the spare parts section and accepts a free-text query parameter alongside mark, model, and region filters. Because the site operates in Russian and Kazakh, search queries should be in one of those languages — for example, фара for headlight or тормозные колодки for brake pads. search_other_categories covers three additional segments via the required category parameter: commercial (trucks and vans), motorcycles, and water (boats and watercraft). Both endpoints return the same paginated summary shape as search_cars.
The Kolesa API is a managed, monitored endpoint for kolesa.kz — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when kolesa.kz changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official kolesa.kz API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Aggregate current used car prices in Kazakhstan by make, model, and region using
search_carsprice fields - Build a cross-border vehicle sourcing tool filtering Kolesa.kz listings by customs cleared status
- Track spare parts availability and pricing for specific makes and models in a given city
- Populate a vehicle lookup UI with make and model hierarchies from
get_makesandget_models - Monitor commercial vehicle inventory in Almaty or other oblasts via
search_other_categorieswith category='commercial' - Pull full vehicle specs and photo galleries for a car detail page using
get_car_listingparams and photos fields - Compare seller listing volumes by region using paginated results from
search_carswith differentregionslugs
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Kolesa.kz have an official public developer API?+
How do I get the correct slug values for make, model, and region filters in search_cars?+
get_makes to get the urlAlias for each brand (e.g. 'toyota', 'bmw'), then pass the numeric id from that response to get_models to get model slugs like 'camry' or 'land-cruiser-prado'. Region slugs come from get_cities, which returns an alias field for each oblast and city (e.g. 'almaty', 'region-almatinskaya-oblast'). The model filter in search_cars requires mark to also be set.What vehicle parameters does get_car_listing return, and what is not included?+
params object in get_car_listing includes city, generation, body type, engine, transmission, drive type, steering wheel side, color, and customs status. VIN numbers, service history records, and inspection reports are not currently exposed by the API. You can fork the API on Parse and revise it to add an endpoint targeting those fields if they become accessible on a listing page.Does the spare parts search support English-language queries?+
search_spare_parts endpoint's query parameter is designed for Russian or Kazakh text, matching the language of the Kolesa.kz spare parts section. English queries are likely to return few or no results. The API currently covers Russian and Kazakh text matching. You can fork it on Parse and revise to add transliteration or translation preprocessing if your application requires English input.Can I retrieve seller contact information such as phone numbers from listings?+
seller object in get_car_listing returns the seller's display name and city. Phone numbers and direct contact details are not currently returned by the API. You can fork it on Parse and revise to add an endpoint that retrieves contact fields if they are available on the listing page without authentication.