search_used_cars
Search AUTO.RIA used-car listings by brand, model, region, fuel, gearbox, and more. Returns matching ad IDs, count, and page info.
Instructions
Search AUTO.RIA used-car listings (passenger cars) by friendly inputs.
Resolves brand/model/region/city/fuel/gearbox/body names to AUTO.RIA
ids for you, then makes a single search call. Returns the total match
count, the current page/page_size, and the matching advert ids
(used cars only — the OfferOfTheDay promo is filtered out). To get a
specific listing's details and its own auto.ria.com URL, pass an id to
get_car_details, or set include_details=true to get them inline.
Notes:
Mileage is in km (e.g.
mileage_to=150000); engine volume is in litres (engine_volume_from=1.9), power in hp (power_hp_from).Engine volume is stored imprecisely upstream (a 2.0 may appear as 1.97), so use a band (e.g. 1.9–2.1) rather than an exact value.
modelrequiresbrand;cityrequiresregion. To target Kyiv city, useregion="Київська", city="Київ"(there is no separate Kyiv region). Filter bygeneration_id/modification_id(fromlist_generations/list_modifications) to isolate a specific generation or engine/trim.v1 supports a single brand+model block. For multi-brand queries use the
raw_searchtool.
Example: search_used_cars(brand="Audi", model="A6", body="Універсал", engine_volume_from=1.9, engine_volume_to=2.1, fuel="Дизель", order_by="price_asc").
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Body style name, e.g. 'Седан', 'Універсал'. | |
| city | No | City name; requires `region`, e.g. 'Жмеринка'. | |
| fuel | No | Fuel type name, e.g. 'Дизель', 'Електро'. 'Гібрид' (or 'hybrid') covers all subtypes (HEV/PHEV/MHEV/REEV) in one call — note this includes MHEV (mild hybrids, essentially ICE); for full/plug-in hybrids pass an exact subtype like 'Гібрид (HEV)' / 'Гібрид (PHEV)'. | |
| page | No | 0-based page number. | |
| brand | No | Brand/marque name, e.g. 'BMW', 'Toyota'. | |
| model | No | Model name; requires `brand`, e.g. '3 Series'. | |
| region | No | Region/oblast name, e.g. 'Київська'. | |
| gearbox | No | Gearbox name, e.g. 'Автомат', 'Ручна / Механіка'. | |
| year_to | No | Latest model year, e.g. 2020. | |
| currency | No | Price currency: USD, EUR, or UAH. | USD |
| order_by | No | Sort order — pass a name (preferred) or the legacy int: relevance (0), price_asc (2), price_desc (3), year_desc (5, newest), year_asc (6), date_desc (7, newest listing), date_asc (8), mileage_desc (12), mileage_asc (13). The default 'relevance' may surface promoted/closest matches first and bury the cheapest or newest; for an exhaustive or price-ranked sweep pass an explicit sort (e.g. 'price_asc') and page through `count`. | relevance |
| price_to | No | Maximum price in `currency`. | |
| page_size | No | Results per page (1-100). | |
| year_from | No | Earliest model year, e.g. 2015. | |
| mileage_to | No | Maximum mileage in km, e.g. 150000. | |
| price_from | No | Minimum price in `currency`. | |
| power_hp_to | No | Max engine power in hp (к.с.). | |
| mileage_from | No | Minimum mileage in km, e.g. 50000. | |
| generation_id | No | Generation id(s) from `list_generations`. Pass several to span facelifts of one generation (e.g. C7, C7 FL). | |
| power_hp_from | No | Min engine power in hp (к.с.). | |
| include_details | No | If true, also fetch each listing on this page (compact details, aligned to `ids`) in one call — removes the usual follow-up `get_car_details_batch`. Costs ~`page_size` extra upstream calls, so keep `page_size` small; capped at page_size<=50. | |
| modification_id | No | Modification id(s) from `list_modifications`. | |
| engine_volume_to | No | Max engine volume in litres, e.g. 2.1. | |
| engine_volume_from | No | Min engine volume in litres, e.g. 1.9. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | ||
| page | No | ||
| count | No | ||
| details | No | ||
| page_size | No |