Ендпойнти

Детайли за автомобила

Fetch a full source payload from cache or, when needed, from the upstream source.

Справочникът на ендпойнтите е на английски, както и самият API.

GET | POST

/api/car-details

Fetch full vehicle detail by source and listing identifier.

Изисква обхвата details scope.

Параметри

sitestring · query string or JSON bodyзадължителен

schadeautos, auto1, openlane, copart, encar, kbchachacha,. Japan has stored auction detail only and is rejected here.

Пример encar·Откъде идва стойността /api/sites -> sites[].name

id / link / identifierstring · query string or JSON bodyзадължителен

Provide any one source id or listing URL. For auto1 use the source offer identifier. KB ChaChaCha requires numeric carSeq. For Japan use the stored auction detail endpoint instead.

Пример 38112900·Откъде идва стойността /api/search -> results[].auction_id, or the source listing URL

search_idstring · query string or JSON body

Optional correlation id.

Пример vehicle-page-42·Откъде идва стойността Optional correlation id generated by your application.

Example requests

Request

GET | POST https://api.thecarapi.com/api/car-details?site=encar&id=38112900

POST https://api.thecarapi.com/api/car-details
{
  "site": "openlane",
  "identifier": "11125938",
  "search_id": "vehicle-page-42"
}

Примерен отговор

json

{
  "success": true,
  "site": "openlane",
  "auction_id": 11409652,
  "current_price": 25900,
  "current_final": 33566,
  "public_price_eur": 33926,
  "vehicle_details": {},
  "auction": {
    "extracted_fields": {
      "images": []
    }
  },
  "live_price": {
    "price": 25900,
    "currency": "EUR",
    "source": "openlane",
    "fetched_at": 1786659750
  }
}

Какво получавате

vehicle_detailsobject | null

The same normalized block /api/auction/{site}/{id} returns, so the two detail endpoints agree. Null when the listing has no fetched details yet. This is the only part of the response with a stable cross-source contract — the remaining keys are source-shaped (data, auction, images, details depending on the source).

details_pendingboolean

True while the upstream fetch is still running — a fetch that outran the request time budget keeps running in the background. Poll rather than retrying in a tight loop. The X-Details-Fetch header carries the same signal as fetched, pending or miss, and is absent when the response was served from stored data. Cache-Control is max-age=5 while pending and max-age=60 once settled.

current_price / current_final / public_price_eurnumber

The same price fields as /api/auction/{site}/{id}, under the same names and with the same JSON types — but at the top level here, because this body is source-shaped and has no auction wrapper. Updates between separate requests can change prices; compare listing timestamps and live_price.fetched_at.

live_price / live_price_pendingobject | boolean

Identical contract to /api/auction/{site}/{id}, and attached the same way when this response is served from stored auction data — the normal case, for a running openlane auction. A first-ever fetch of a listing we hold no row for returns the source’s own fresh payload anyway.

auctionobject

Not the vehicle record. For openlane this is { extracted_fields: { images: […] } }, an image container that shares a name and nothing else. Read prices from the top level on this endpoint, and from inside auction on /api/auction/{site}/{id}.

estimated_value_eurnumber | null

Optional auction-house valuation in EUR where available. Treat it as an estimate, never a price you can pay or a settled result. Do not substitute it for current_price.

steeringenum | null

Same derivation and spelling as the search cards and /api/auction/{site}/{id}, published at the top level here. Null only when the vehicle is not in our inventory at all, because there is then no registration country to derive a side from.

Бележки

Parameters may be sent in the query string or a JSON body. This endpoint can be slower than canonical auction detail. Fee, transport, delivery and account-scoped fields are stripped here exactly as they are on auction detail. When no details are stored yet it fetches from the source during the request and returns what it just stored, rather than an empty shell — read details_pending in the body and X-Details-Fetch in the headers (fetched, pending, or miss; absent when served from stored data), and poll rather than retrying in a tight loop. This response carries no envelope metadata — no contract_version, request_id, server_time or data_updated_at in the body. Read the correlation id from the X-Request-ID header. The response also carries X-Data-Source (auctions, car_details_cache or scraped) telling you which path answered, and X-Cache-Age in seconds on a cache hit. Everything outside vehicle_details and the price fields is source-shaped (data, auction, images, details depending on the source); those two are the parts with a stable cross-source contract. Live prices apply here too when the response comes from stored auction data; note the one trap that catches people — for openlane this body’s auction key is an image container, not the vehicle record, so prices are read from the top level. If the source reports the listing is gone, that surfaces as a 404 rather than a 500.

GET | POST

/api/listVehicles

Catalog-shaped listing feed — a compatibility alias for search.

Изисква обхвата details scope.

Параметри

page / page_sizeinteger · query string or JSON body

1-based page and rows per page, as alternatives to offset and limit. Do not combine page with offset or page_size with limit.

Пример 1 / 50·Откъде идва стойността Pagination state in your application.

manufacturer_slug / manufacturer / brandstring · query string or JSON body

Brand, under any of the three accepted spellings.

Пример bmw·Откъде идва стойността /api/catalog/manufacturers -> results[].slug

model_group_slug / model_group / modelstring · query string or JSON body

Model group, under any of the three accepted spellings.

Пример 320d·Откъде идва стойността /api/catalog/model-groups?manufacturer__slug=bmw -> results[].slug

fuel_type / fuelstring · query string or JSON body

Canonical fuel group.

Пример Diesel·Откъде идва стойността /api/fuels -> fuels[]

steeringenum · query string or JSON body

Left- or right-hand drive, in any of the spellings /api/search accepts.

min_year / max_yearinteger · query string or JSON body

Registration-year range.

Пример 2018 / 2024·Откъде идва стойността Year bounds chosen by your user.

max_mileageinteger · query string or JSON body

Mileage ceiling.

Пример 120000·Откъде идва стойността Mileage ceiling chosen by your user.

orderingstring · query string or JSON body

Sort order. An unrecognised value silently falls back to the default (photo-first, then newest) rather than erroring.

Пример -created_at·Откъде идва стойността created_at / created / published_at, price / price_eur, year / date_first_registration, each with an optional leading minus.

limit / offsetinteger · query string or JSON body

Or page_size / page. Default limit 50. No offset cap.

Пример 50 / 0·Откъде идва стойността Pagination state in your application.

Example requests

Request

GET | POST https://api.thecarapi.com/api/listVehicles?manufacturer_slug=bmw&model_group_slug=320d&max_mileage=120000

GET | POST https://api.thecarapi.com/api/listVehicles?brand=audi&min_year=2019&ordering=price&limit=50

Примерен отговор

json

{
  "success": true,
  "vehicles": [],
  "results": [],
  "total": 210,
  "limit": 50,
  "offset": 0,
  "total_pages": 5,
  "max_page": 5
}

Какво получавате

vehicles / resultsobject[]

The same array object served twice under two names for compatibility. Read either one, not both. Each row is a standard search result card plus four catalog-shaped keys: vehicle_id (the same value as auction_id — subject to the same 2^53 caveat, prefer auction_id_str), manufacturer_slug (slug of clean_make), model_group_slug (slug of clean_model), and fuel_type (normalized fuel, present only when the row carries one). Rows carry the same 8-photo images preview cap as /api/search.

total / limit / offset / page / page_size / total_pages / max_pageinteger | null

Standard pagination fields. There is no offset cap — max_page equals total_pages, as on /api/search. Default limit 50.

Бележки

A compatibility alias kept for older integrations, also reachable at /listVehicles, and accepted as GET (query string) or POST (JSON body) with the same fields. Not enabled on a new key by default — ask for it. New integrations should use /api/search, which has more filters, cheaper counts, ETags and a stable envelope. This route exists so older clients keep working. ordering understands three fields, each with an optional minus for descending: created_at / created / published_at (default, photo-first then newest), -created_at / -created / -published_at (newest), price / price_eur (price_low), -price / -price_eur (price_high), year / date_first_registration (year_old), -year / -date_first_registration (year_new). An unrecognised value silently falls back to the default order rather than erroring. The response carries no envelope metadata and is sent Cache-Control: no-store, so it is never revalidated with an ETag.