Търсене и откриване
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.
Справочникът на ендпойнтите е на английски, както и самият API.
Primary filtered search over live auction inventory.
Изисква обхвата search scope.
Параметри
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.
Пример 4,4.5,5·Откъде идва стойността 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.
Пример uss,honda_tokyo·Откъде идва стойността 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.
Пример 80041·Откъде идва стойността 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.
Пример USF40,ZC6·Откъде идва стойността 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.
Пример 2019 / 2024·Откъде идва стойността /api/production-years
typestring · query stringTrim/type filter, distinct from vehicle_type and body_style. Accepts multiple comma-separated values; unclassified trims are retained.
Пример Touring·Откъде идва стойността /api/types?brand=bmw&model=320d
searchstring · query stringFree-text brand, model, or keyword query.
Пример BMW 320d·Откъде идва стойността 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.
Пример encar·Откъде идва стойността /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.
Пример copart·Откъде идва стойността /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.
Пример bmw·Откъде идва стойността /api/brands -> brands[].slug (or id/name)
modelstring · query stringModel name or slug.
Пример 320d·Откъде идва стойността /api/models?brand=bmw -> models[].slug
year_from / year_tointeger · query stringRegistration-year range.
Пример 2018 / 2024·Откъде идва стойността /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.
Пример Diesel·Откъде идва стойността /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.
Пример Automatic·Откъде идва стойността /api/gearboxes -> gearboxes[]
countrystring · query stringISO country code or europe.
Пример DE·Откъде идва стойността /api/countries -> country_details[].code
vehicle_typestring · query stringcars or suvs & trucks.
Пример cars·Откъде идва стойността Choose from the documented vehicle_type enum.
body_stylestring · query stringBody-style filter.
Пример sedan·Откъде идва стойността 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.
Пример left·Откъде идва стойността 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.
Пример 0 / 80000·Откъде идва стойността Mileage range chosen by your user.
horsepower_from / horsepower_tointeger · query stringHorsepower range.
Пример 150 / 300·Откъде идва стойността Horsepower range chosen by your user.
price_from / price_tointeger · query stringPublic EUR price range.
Пример 10000 / 30000·Откъде идва стойността EUR budget chosen by your user.
damagedboolean · query stringReturn damaged or broken vehicles only.
Пример true·Откъде идва стойността Your filter choice.
buy_nowboolean · query stringReturn Buy-Now listings only.
Пример true·Откъде идва стойността Your filter choice.
ending_soonboolean · query stringReturn auctions ending within about two hours.
Пример true·Откъде идва стойността Your filter choice.
smart_filterenum · query stringtop_offers, low_mileage, or best_value.
Пример best_value·Откъде идва стойността 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.
Пример true·Откъде идва стойността 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.
Пример true·Откъде идва стойността 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.
Пример price_low·Откъде идва стойността 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.
Пример 24·Откъде идва стойността Page size chosen by your application.
offset / pageinteger · query stringOffset-based or page-based pagination.
Пример 24 / 2·Откъде идва стойността Current page state in your application.
include_totalboolean · query stringSet false to skip the count. Default true.
Пример false·Откъде идва стойността Your performance/display choice.
count_onlyboolean · query stringReturn counts without result rows.
Пример true·Откъде идва стойността 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=20Примерен отговор
{
"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"
}Какво получавате
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.
Изисква обхвата search scope.
Параметри
qstring · query stringFree-text query. An empty or missing query returns an empty list, not a 400.
Пример bmw 320d touring·Откъде идва стойността 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%20ev6Примерен отговор
{
"success": true,
"auction_ids": [
38112900,
11409652
],
"found": 2
}Какво получавате
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.