Search & discovery
Search live auction inventory, then resolve lightweight full-text matches. Only live lots are returned. include_ended=true also shows lots whose clock has run out but that have not been archived yet; finished auctions are searched with /api/archive/search.
Primary filtered search over live auction inventory.
Requires the search scope.
Parameters
auction_gradestring · query stringThe Japanese auction house's grade, as a comma-separated list of the grades to keep: `S`, `6`, `5`, `4.5`, `4`, `3.5`, `3`, `2`, `1`, `R` and `RA` (repaired) and `***` (ungraded). Matched exactly, not as a minimum, because the letters have no place on the numeric scale. Case and full-width digits are folded; any other value is a 400 on `/api/search` and `/api/archive/search`, and ignored by the facet endpoints. Only Japanese listings carry a grade, so any value keeps only them. The grade is the resellers' where they state one they agree on, else the one read off the lot's auction sheet. It is published on each result as `auction_grade`. Not in the precomputed search index, so a request that sends it is served by the live query and is slower.
Example 4,4.5,5·Where the value comes from Listing values or your application settings.
auction_housestring · query stringThe Japanese auction house, as a comma-separated list of names in the slug form each result's `auction_house` carries (`uss_tokyo`, `honda_tokyo`). Spaces, case and punctuation are folded, so `HONDA TOKYO` works too. Matches whole words of the house name: `uss` finds every USS branch, `tokyo` every Tokyo house, `uss_tokyo` that one house; `oky` finds nothing. A value that is not a Latin-script name is a 400 on `/api/search` and `/api/archive/search`, and ignored by the facet endpoints. Only Japanese listings carry a house, so any value keeps only them. Not in the precomputed search index, so a request that sends it is served by the live query and is slower.
Example uss,honda_tokyo·Where the value comes from Listing values or your application settings.
lot_numberstring · query stringThe Japanese auction house's lot number, as a comma-separated list. Leading zeros and full-width digits are folded (`080041` finds `80041`); a value that is not letters and digits is a 400 on `/api/search` and `/api/archive/search`, and ignored by the facet endpoints. Only Japanese listings carry a lot number, so any value keeps only them. A house numbers its lots per sale day, so one number can match several cars: tell them apart by `auction_house` and `batch_end_date` (the sale day) on each result. It is published on each result as `lot_number`. Not in the precomputed search index, so a request that sends it is served by the live query and is slower.
Example 80041·Where the value comes from Listing values or your application settings.
model_codestring · query stringA Japanese lot's chassis model code (e.g. `USF40`, `ZC6`), as a comma-separated list. Compared without case or punctuation, so `u-30-5` finds `U-30-5`. A value with no letters or digits is a 400 on `/api/search` and `/api/archive/search`, and ignored by the facet endpoints. Only Japanese listings carry a model code, so any value keeps only them. Published on each result as `model_code`. Not in the precomputed search index, so a request that sends it is served by the live query and is slower.
Example USF40,ZC6·Where the value comes from Listing values or your application settings.
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 stringOnly true, the default, is accepted. false is a 400: this endpoint returns live lots only. For finished auctions use /api/archive/search.
Example true·Where the value comes from Your filter choice.
include_endedboolean · query stringDefault false. true also shows lots whose clock has run out but that have not been archived yet. Also accepts 1/0/yes/no.
Example true·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. Default 100, maximum pagination.max_limit from /api/contract — 100, or up to 500 on a key granted bulk pages. Larger values are clamped down.
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-10-05"
}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.