Search & discovery
Search live auction inventory, then resolve lightweight full-text matches. Ended lots are hidden by default; is_active=false / include_ended=true shows them as well as live ones.
Primary filtered search over live auction inventory.
Requires the search scope.
Parameters
production_year_from / production_year_tointeger · query stringProduction-year bounds. Falls back to registration year when the source provides no production year.
Example 2019 / 2024·Where the value comes from /api/production-years
typestring · query stringTrim/type filter, distinct from vehicle_type and body_style. Accepts multiple comma-separated values; unclassified trims are retained.
Example Touring·Where the value comes from /api/types?brand=bmw&model=320d
searchstring · query stringFree-text brand, model, or keyword query.
Example BMW 320d·Where the value comes from Free text entered by your user.
sitestring · query stringComma-separated source slugs, OR within the parameter. Case-insensitive. An unknown slug is a 400 naming the offender — one bad member rejects the whole list.
Example encar·Where the value comes from /api/sites -> sites[].name
site_excludestring · query stringComma-separated source slugs to leave out. Sent alongside site, it narrows the include list; excluding everything you included is a 400, not an empty page.
Example copart·Where the value comes from /api/sites -> sites[].name
brandstring | integer · query stringBrand display name, slug, or brand_id — all three select the same inventory. Matched on the brand identity rather than the published spelling, so sources that write it differently (openlane publishes "Volkswagen" where others write "VW") are all included.
Example bmw·Where the value comes from /api/brands -> brands[].slug (or id/name)
modelstring · query stringModel name or slug.
Example 320d·Where the value comes from /api/models?brand=bmw -> models[].slug
year_from / year_tointeger · query stringRegistration-year range.
Example 2018 / 2024·Where the value comes from /api/years -> years[]
fuelstring · query stringCanonical fuel group, matched whole. Hybrid, Mild Hybrid and Plug-in Hybrid are three separate groups — fuel=Hybrid returns full hybrids only. A lot with no recorded fuel matches every fuel filter rather than none, so it stays reachable.
Example Diesel·Where the value comes from /api/fuels -> fuels[]
gearboxstring · query stringCanonical gearbox group, matched whole. Same unknown-matches-all rule as fuel: a car with no recorded gearbox answers every gearbox filter.
Example Automatic·Where the value comes from /api/gearboxes -> gearboxes[]
countrystring · query stringISO country code or europe.
Example DE·Where the value comes from /api/countries -> country_details[].code
vehicle_typestring · query stringcars or suvs & trucks.
Example cars·Where the value comes from Choose from the documented vehicle_type enum.
body_stylestring · query stringBody-style filter.
Example sedan·Where the value comes from Your application's normalized body-style value.
steeringenum · query stringLeft- or right-hand drive. The parameter takes two values, each with four equivalent spellings. Every listing resolves to one side or the other, so the two values partition the inventory and their counts sum to the unfiltered total.
Example left·Where the value comes from left | lhd | left-hand | left_hand, or right | rhd | right-hand | right_hand — any other value is a 400.
kilometers_from / kilometers_tointeger · query stringMileage range.
Example 0 / 80000·Where the value comes from Mileage range chosen by your user.
horsepower_from / horsepower_tointeger · query stringHorsepower range.
Example 150 / 300·Where the value comes from Horsepower range chosen by your user.
price_from / price_tointeger · query stringPublic EUR price range.
Example 10000 / 30000·Where the value comes from EUR budget chosen by your user.
damagedboolean · query stringReturn damaged or broken vehicles only.
Example true·Where the value comes from Your filter choice.
buy_nowboolean · query stringReturn Buy-Now listings only.
Example true·Where the value comes from Your filter choice.
ending_soonboolean · query stringReturn auctions ending within about two hours.
Example true·Where the value comes from Your filter choice.
smart_filterenum · query stringtop_offers, low_mileage, or best_value.
Example best_value·Where the value comes from Choose from the documented smart_filter enum.
is_activeboolean · query stringDefault true: lots whose auction has closed are hidden. false shows closed lots in addition to live ones — it does not return only ended lots, and it is not a filter on the is_active response field.
Example false·Where the value comes from Your filter choice.
include_endedboolean · query stringThe same switch inverted: include_ended=true equals is_active=false. Default false. If both are sent, include_ended wins.
Example false·Where the value comes from Your filter choice.
sortenum · query stringSort value from the data dictionary. Default default — photo-first, then newest. The retired random value is still accepted and is served as default.
Example price_low·Where the value comes from Choose from the documented Sort enum.
limit / page_sizeinteger · query stringPage size, maximum 100. Default 100.
Example 24·Where the value comes from Page size chosen by your application.
offset / pageinteger · query stringOffset-based or page-based pagination.
Example 24 / 2·Where the value comes from Current page state in your application.
include_totalboolean · query stringSet false to skip the count. Default true.
Example false·Where the value comes from Your performance/display choice.
count_onlyboolean · query stringReturn counts without result rows.
Example true·Where the value comes from Your response-mode choice.
Example requests
GET https://api.thecarapi.com/api/search?brand=bmw&fuel=Diesel&year_from=2018&sort=price_low&limit=24GET https://api.thecarapi.com/api/search?site=encar&country=KR&buy_now=true&page=2&page_size=20Example response
{
"success": true,
"results": [
{
"auction_id": 38112900,
"site_name": "encar",
"clean_make": "BMW",
"clean_model": "320d",
"registration_year": 2020,
"mileage": 45000,
"public_price_eur": 21500,
"thumbnail_url": "https://cdn.example/photo.webp"
}
],
"total": 18342,
"limit": 24,
"offset": 0,
"count_only": false,
"page": 1,
"page_size": 24,
"total_pages": 764,
"max_page": 764,
"secret_mode": false,
"contract_version": "2026-09-03"
}What you get back
results[]object[]Search result cards. The full allowlisted field set is in the data dictionary; fields are present when the source provides them. Address a car by auction_id_str, not auction_id — japan ids exceed 2^53, so a client parsing JSON numbers as doubles silently rounds the numeric one.
results[].imagesobject[]At most the first 8 display-ordered gallery entries, primary first. This is a card preview, never the full gallery — read vault_gallery on the detail response or /api/auction-images/{site}/{id} for everything.
totalinteger | nullTotal matching rows, counting the same lots the pages return — so paging to total_pages does not run into short or empty pages. Null when include_total=false or totals are suppressed.
limit / offsetintegerThe window that was actually applied, echoed back. On a count_only=true response both are 0.
page / page_size / total_pages / max_pageinteger | nullThe same window in page terms, plus total pages and the deepest reachable page. All four are null on a count_only response, which has no pages to describe. max_page equals total_pages here — /api/search has no offset cap.
count_onlybooleanEchoes the parameter. On true the rows are omitted and only total remains.
secret_modebooleanLegacy field, always false. Ignore it.
contract_versionstringSchema contract the response was built against.
request_id / server_time / data_updated_atstringCorrelation id (also X-Request-ID), response time, and when the underlying data was last refreshed.
Resolve a free-text query to matching auction ids only.
Requires the search scope.
Parameters
qstring · query stringFree-text query. An empty or missing query returns an empty list, not a 400.
Example bmw 320d touring·Where the value comes from Free text entered by your user.
Example requests
GET https://api.thecarapi.com/api/search/auction-ids?q=bmw%20320dGET https://api.thecarapi.com/api/search/auction-ids?q=kia%20ev6Example response
{
"success": true,
"auction_ids": [
38112900,
11409652
],
"found": 2
}What you get back
auction_idsinteger[]Bare auction_id values with no source attached. An id is only unambiguous if it happens to be unique across sources — which is exactly what /api/auction/{site}/{id} needs a site for. Use this as a filter, not as an addressing scheme; hydrate through /api/search?search= instead, which returns whole cards carrying site_name and auction_id_str.
foundintegerLength of auction_ids. The whole match set is returned, capped at 10,000 ids — there is no paging.