Fields by source

Eight inventory sources feed one API, and they do not publish the same things. A German wholesale platform ships a full inspection report and a DAT equipment catalogue; a Japanese export lot ships an auction inspection sheet and a condition grade; Korean listings carry specifications and optional condition evidence. This page is the honest map of who gives you what, so you can decide what your product can promise before you build it.

Three layers of data

Every vehicle in the API is described at three levels of normalization. Knowing which layer a field lives on tells you immediately how portable it is.

The common core is guaranteed in the sense that the field is always in the contract; an individual value can still be null when a particular source does not publish it. fuel_group, for example, is empty for most Japanese lots — and a lot with no recorded fuel matches every fuel filter rather than none, so filtering by fuel never makes those lots unreachable.

What each source gives you

Read this table before you scope a feature. "Sparse" is not a bug to report — it is what the auction house publishes.

Condition data: the coverage matrix

This is the table people actually need. It says which keys of vehicle_details you can expect from which source. Blank means the current integration does not promise that field. It may be unavailable upstream, not yet enriched, or omitted by permissions; absence is not a clean-condition verdict.

Source-specific notes worth knowing

eCarsTrade — blind auctions and the estimate

Most eCarsTrade auctions are blind: every bid is private, so no price is published anywhere and none is inferred. On such a lot current_price, start_price and buy_now_price are all null — and that is the correct, final answer, not a missing value to retry for. You do not have to infer it: the detail response carries is_blind: true, which is the one reliable way to tell "there will never be a price" from "there is no price right now". A client that renders "price unavailable, retrying…" without reading this flag retries forever.

What a blind lot often does carry is estimated_value_eur, the auction house's own valuation (its "eCT Estimation Price"). It is frequently the only number on the lot, which makes it tempting to render in a price slot. Do not. No bid is settled against it and no car is sold at it — a client that shows it as a price quotes customers a figure the auction will not honour. Label it explicitly as an estimate, and never sort or filter on it: it is null for every other source and on eCarsTrade lots without a published valuation, so any ordering that uses it silently drops them.

{
  "auction_id": 7479712,
  "site_name": "ecarstrade",
  "current_price": null,
  "start_price": null,
  "buy_now_price": null,
  "estimated_value_eur": 12000.0
}

Japanese auctions — the price is an opening bid

A live Japanese lot has no hammer price until it closes, so current_price on japan is the opening bid, not a cost. Some lots publish no opener, and conflicting imported prices are withheld. Nominal starters can be far below the eventual price. Read it as a floor. buy_now_price is never set on this source, and best-value ranking will flag some of these lots optimistically as a result.

Japanese rows carry origin JP. Use country=JP or site=japan, and /api/auction/japan/{id} for stored details. /api/car-details does not accept Japan. Use the string id from search without converting it to a JavaScript number.

OpenLane — report types

OpenLane classifies each report it publishes. type is the readable name and type_id the source's raw code.

Auto1's single inspection report is normalized into the same list with type inspection_report and no type_id. eCarsTrade's appraisal links arrive under documents rather than here, because the source itself presents them as documents.

Japanese auctions — the auction sheet

Japanese auction sheets and photos are optional imported evidence. Use the returned gallery and available report entries; the current importer does not promise a normalized auction_sheet entry on every lot, an extracted VIN, or live upstream detail fetching. The source specification and matched reseller evidence remain under car_identification; imported sheet URLs are under JapanMerged.AuctionSheetUrls.

Opening and downloading reports

Follow the exact returned /report-vault/{site}/{auction_id}/{token} URL; the token identifies an already-known report and is not an upstream URL you can construct. This delivery route currently needs no API key. A successful response is a binary file with its Content-Type, not a JSON envelope. download=1 requests an attachment. A 302 points to an upstream page; a 400 means an invalid token, a 404 means no matching report, and a 503 means the backing database is unavailable. Do not forward your API key to an upstream redirect target.

KB ChaChaCha — diagnosis and inspection

Read vehicle_details.kb_diagnosis and vehicle_details.kb_inspection independently: one report can be available while the other is unavailable. They preserve the source evidence rather than turning it into a universal accident score. Use the numeric carSeq for /api/car-details?site=kbchachacha&id=..., or the exact stored identifier from a search card for /api/auction/kbchachacha/{id}.

Naming collisions to be aware of

The same word means different things upstream, which is precisely why the normalized block exists. A downloadable file is Documents[] on Auto1 but ECarsTradeDocuments[] on eCarsTrade — while Documents on OpenLane is a dictionary of paperwork booleans and not a file list at all. If you read car_identification directly, you own that problem. If you read vehicle_details.documents, you do not.

Steering side

steering is normalized to left or right. Explicit source evidence is used where supported; otherwise it is inferred from registration market. It is an inferred field where no explicit source value exists, not a universal physical inspection guarantee. Japanese imports may include left-hand-drive vehicles, so do not derive steering from country in your client.

Because every listing resolves to one side or the other, the two values partition the inventory: their counts sum to the unfiltered total. As a filter it takes two values, each with four equivalent spellings — left, lhd, left-hand, left_hand and right, rhd, right-hand, right_hand — and anything else is a 400. It is accepted by /api/search, /api/top-offers, /api/listVehicles and every facet endpoint — though on a facet endpoint it is computed live rather than read from the precomputed table, so it is slower than an unfiltered facet call.

Writing code that survives the differences

// Right: ask for the key, accept its absence, never branch on the source.
function conditionSummary(auction) {
  const d = auction.vehicle_details ?? {};

  return {
    // Present on auto1 and openlane; free text on ecarstrade; absent elsewhere.
    damages: d.damages ?? [],
    damageNotes: d.damage_comment ?? d.technical_issues ?? null,

    // ecarstrade is the only source with per-visit rows. Everyone else has a summary.
    serviceVisits: d.service_history ?? null,
    serviceSummary: d.service_history_summary ?? null,

    // Most listings carry no reports at all. Empty is normal, not an error.
    reports: d.inspection_reports ?? [],

    repairCost: d.estimated_repair_costs ?? null,
  };
}

// Wrong: this breaks the day a source is added, and hides data today.
if (auction.site_name === "auto1") { /* ... */ }

• Never hardcode the source list. Read it from /api/sites at startup. An unknown slug is a 400 naming the offender, so a stale hardcoded list turns a new source into a broken deploy.
• Design for the shallowest source you serve. No source guarantees full service history on every car. eCarsTrade can provide per-visit rows where available. Promise it where it exists and degrade gracefully where it does not.
• Treat car_identification as unversioned. Its keys follow each upstream's own naming and change when the upstream changes. Anything you depend on long-term should come from the common core or vehicle_details.
• details_pending: true is not an error. It means the detail payload has not been assembled yet. Poll rather than retrying in a tight loop, and render the card data you already have.