Search & discovery
Search live and archived auction inventory, then resolve lightweight full-text matches.
Primary filtered search over live auction inventory.
Requires the search scope.
Parameters
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.
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.
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. left/lhd and right/rhd are 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 | right | rhd — 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 conventions section.
Example price_low·Where the value comes from Choose from the documented Sort enum.
seedstring · query stringStable random seed, up to 64 URL-safe characters.
Example k9f2ab·Where the value comes from Previous search response -> random_seed
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,
"total_pages": 764,
"max_page": 764,
"random_seed": "k9f2ab",
"contract_version": "2026-08-19"
}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.
totalinteger | nullTotal matching rows. Null when include_total=false or totals are suppressed.
limit / offsetintegerThe window that was actually applied, echoed back.
total_pages / max_pageinteger | nullTotal pages, and the deepest page reachable under the depth policy.
random_seedstring | nullNon-null only when the effective sort is random. Pass it back as seed= to page through the same ordering.
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 query returns an empty list.
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": [
"encar:38112900",
"auto1:AB12CD"
],
"found": 2
}