Auctions & history

The image vault’s authoritative photo set, embedded verbatim: the exact body of /api/auction-images/{site}/{id} ({ images, count, pending }). Read it and a detail page is one request instead of two. Both routes build it from one cache entry, so they can never disagree; while pending is non-zero this response is served with max-age=10 so a polling client sees photos as they land. A client that ignores it behaves exactly as before.

Cross-source normalized condition and paperwork: documents, inspection_reports, option_reports, car_reports, service_history, technical_inspection, paperwork, condition, damages, equipment, warranty, specs, location, seller, profile. Every key is omitted when the source has nothing for it, and the whole block is omitted for a listing whose details have not been fetched yet (details_pending: true).

Raw source-specific spec map. Prefer vehicle_details where it covers what you need — its keys are stable across sources, these are not.

What the source record itself carried — untouched by this release. For the vault’s photo set with served URLs and dimensions, read vault_gallery above.

Present when a live bid overlay is available, including a recent cached bid within the TTL: { price, currency, source, fetched_at }. price is the raw bid and equals current_price; fetched_at is a Unix timestamp in seconds — use it, not your own clock, to render “as of”. Its absence is not an error: it means the car is served at its cycle price, which for most listings is the only price there is.

True when the refreshed figure was not to hand in time for this response — your request is never held waiting on the auction house. Read the car once more after ~2s and then stop; the second read is served from cache. These responses carry Cache-Control: no-store and X-Live-Price: pending. This is the only case worth reading again for, and the only case that sets the flag.

JSON numbers, always. Recomputed from the bid when a live price happened, so a client that ignores live_price entirely still shows the right number. buy_now_price and buynow_final are never touched — a buy-now figure does not move with bidding.

The auction id as a string — the one to persist and to address the car with. japan ids exceed 2^53, so JavaScript and any other client parsing JSON numbers as IEEE-754 doubles silently rounds the numeric auction_id and the result no longer addresses the row it came from. auction_id is unchanged and stays a number for existing consumers.

The same four catalog-shaped keys /api/listVehicles adds. vehicle_id is a duplicate of auction_id (same 2^53 caveat — prefer auction_id_str). manufacturer_slug and model_group_slug are the values the catalog routes are addressed by, so a detail response is enough to build a link to its manufacturer and model-group pages without a second lookup. fuel_type is present only when the row carries a fuel.

True when the auction house publishes no bid at all, by design — most eCarsTrade auctions. This is the one case where current_price: null is a final answer rather than missing data: there is no figure to fetch, now or later, and no live price will ever arrive. Read it before rendering "price unavailable, retrying…", which on a blind lot retries forever; show estimated_value_eur instead, labelled as an estimate.

True while the full detail payload has not been fetched from the source yet. vehicle_details is omitted meanwhile and the response carries a short max-age so a polling client sees the details land. Not an error.

Absolute UTC instant the lot closes, or null for stock with no deadline. Drive countdowns from this — not from batch_end_date, whose timezone differs per auction house, nor auction_sec_left, which is a snapshot taken at the last refresh rather than seconds from now.

The auction house own valuation of the vehicle, in EUR — and NOT a price you can pay. No bid is settled against it and no car is sold at it. Only ecarstrade publishes one (its "eCT Estimation Price"); it is null for every other source and may be null on eCarsTrade lots without a valuation. Where it does appear it is often the only number on the lot, because a blind auction hides the bid: current_price, start_price and buy_now_price are all null while this carries the estimate. Label it as an estimate wherever you show it, and never sort or filter on it — it is absent on most cars, so any ordering that uses it silently drops them.

left or right, never null. japan is the only source that publishes a steering field; for every other source the side is read off the car registration market — a car registered in a country that drives on the left (GB, IE, JP, CY, MT, AU, NZ, ZA, IN, TH, HK, SG) is right, everything else left. Also present on every search result card and on /api/car-details.

CO2 in g/km as the auction house measured and published it. Null on roughly half of lots, which publish none. It carries no standard tag and mixes both EU test cycles by registration year — see the CO2 & emissions page.

A derived CO2 figure for lots that publish none, inferred from other lots of the same specification. NEVER a measured value, and null wherever the specification does not decide it. It is a separate field from co2 on purpose, so an estimate can never be mistaken for a measurement.

NEDC or WLTP — which EU test cycle co2_estimated is expressed on. Always read the estimate together with this: the same physical car reads 12-25% higher under WLTP, so a figure without its standard is not comparable.

Auto1 only, and the reason an Auto1 car has a VIN at all: Auto1 publishes no chassis number but photographs the registration certificate, so the VIN is read off that paperwork. { vin, confidence, evidence } — confidence is high, stored or medium, and evidence identifies the document photo it was read from. A high or stored read also fills chassis_number when the row has none, so a client that only reads chassis_number needs no change. A medium read is labelled and never promoted to the car identity: show it as unconfirmed. Roughly 41% of Auto1 cars with a document photo end up with a published VIN — the ceiling is upstream, because Auto1 blurs the VIN field on ES, IT and PT certificates. Part of the vehicle_identity field grant.

True when a VIN read was queued by this request and was not finished in time to answer it — your request is never held waiting on OCR. Read the car once more after a second or two and then stop; the answer is cached for a day once found. Behaves exactly like live_price_pending, and like it, is never an error.

Korean sources only. The same car is often listed on both Encar and KB ChaChaCha; listings are grouped on a shared VIN, or a corroborated plate with make and model, and one is published while the rest are hidden. This block is the evidence: offers (every listing for the car, each with site, auction_id, price_eur, offer_link and eligible), selected (the one published), spread_eur (highest minus lowest eligible price — what the same car costs on the cheaper source), image_source (the listing the gallery came from; photo sets from two listings are never interleaved) and match_method (vin or plate_make_model). Requires the korea_merge field grant.

Present on a Korean listing that was resolved as a duplicate: { site, auction_id } for the representative published in its place. Also behind the korea_merge field grant.

Exactly three values: initial (the first prices we ever recorded for this lot), baseline (the state before the first observed change, written once so a series never starts mid-move), and change (a subsequent movement). There is no price_change value — a client matching on that has been discarding every event.

Which price fields moved in this event. Always an array, empty on a baseline row.

The full price snapshot as of observed_at. JSON numbers or null.

Currency of the source-side figures.

When the change was observed. The field to plot against.

When the row was written. Within seconds of observed_at; not a second data point.

How many photos this response carries.

How many photos the auction still owes. Show placeholders for these instead of a silently short gallery.

The best URL available right now — served_url once vaulted, remote_url until then.

A path, not an absolute URL. It begins /image-vault/… and is relative to the API base, so join it: https://api.thecarapi.com + served_url. Load this directly once the photo is stored.

Always absolute — the source’s own URL. Load this through an image proxy until the photo is vaulted.

ready, pending, downloading, failed, blocked, or not_downloaded — but on this endpoint it is always ready, because only stored photos are listed at all. The other values appear on the image annotations attached to search cards, where a photo can still be in flight. failed and blocked mean the photo exhausted its retries and is not counted in pending, so a gallery can settle with pending: 0 and still be shorter than picture_count.

downloaded (in the vault) or proxied (still served from the source).

Gallery order and which photo is the thumbnail.

Section the source filed the photo under, e.g. exterior, interior, damage.

Pixel dimensions of the stored photo.

camelCase and legacy twins of served_url, thumbnail and index, kept for older clients and always equal to their counterparts. Prefer the snake_case names — the twins may be retired.

local_status is the same value as image_status; local_rel_path is the vault path served_url is built from.

Which source and lot. source_auction_id is the Auto1 batch id where one exists, otherwise the auction id as text.

The VIN as the source published it (punctuation and case as stored).

Normalized identity.

Registration date and the mileage recorded on that appearance.

The whole price block. JSON numbers or null.

Currency of the source-side figures.

Lifecycle. archived_at is null on a live row.

Whether the lot is still open, and its listing URL.

True when this appearance comes from the archive rather than live inventory.