Data dictionary

Search result card fields

Fields are returned when the selected source provides them.

auction_id, site_name, auction_batch_id, batch_start_date, batch_end_date,
auction_sec_left, buy_now_price, car_country_extended, country_code,
country_marker_code, country_marker_name, country_marker_color, car_name_en,
current_price, buynow_final, current_final, buynow_bgn, current_bgn,
date_first_registration, has_technical_damage, is_broken, is_buy_now, kw,
mileage, start_price, final_price, thumbnail_url, hp, pk, size, picture_count,
clean_make, clean_model, model_display, model_class_series, fuel_group,
gearbox_group, clean_type, registration_year, production_year, production_month, is_margin, public_damage_state, public_price_eur,
offer_link, is_active, is_top_offer, top_offer_savings_pct, top_offer_savings

Four more fields are derived rather than stored. The first three are on every row; the fourth appears once the photo is on our CDN.

Rows also carry image annotations alongside the thumbnail: thumbnailUrl and servedThumbnailUrl (camelCase twins of the fields above), image_status and image_source as on gallery entries, original_thumbnail_url (the source's own thumbnail, when the vault's replaced it), and images — at most the first 8 display-ordered gallery entries, primary first. images on a search row is a card preview, never the full gallery: for everything, read vault_gallery on the detail response or /api/auction-images/{site}/{id}.

fuel_group can be empty — japan publishes no fuel for most of the catalogue — and a lot with no known fuel matches every fuel filter rather than none, so filtering by fuel does not make those lots unreachable.

Additional auction detail fields

car_id, chassis_number, co2, co2_estimated, co2_estimated_standard,
buynow_tax, current_tax, buynow_tax_delivery, current_tax_delivery,
cylinder_capacity, effluent_standard_group_search, is_margin,
requested_sales_price, requested_sales_price_can_be_shown, special_price, places,
seller_score, country_code_dealer, community_name, community_seller_name,
currency_code_id, vehicle_grade_id, mechanical_indicator_id, is_commercial_car,
car_identification, car_report_types, images, gallery_images, created_at,
updated_at, first_seen_at, last_seen_at, last_available_at, last_changed_at,
vehicle_details, vault_gallery, estimated_value_eur, is_blind, details_pending

It also carries auction_id_str, auction_end_at and steering, exactly as the search cards do, plus the same four catalog-shaped keys /api/listVehicles adds: vehicle_id (a duplicate of auction_id, and subject to the same 2^53 caveat — prefer auction_id_str), manufacturer_slug, model_group_slug and, where the row has one, fuel_type. The two slugs 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.

`is_blind` and `details_pending`

Two booleans answer questions the rest of the payload cannot.

is_blind is true when the auction house publishes no bid at all, by design. 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. Most eCarsTrade auctions are blind. A client that shows "price unavailable, retrying…" on a blind lot will retry forever; read this flag and show estimated_value_eur instead, labelled as an estimate.

details_pending is true when the listing's full detail payload has not been fetched from the source yet. While it is true, vehicle_details is omitted and the response is served with a short max-age so a polling client sees the details land. It is not an error and needs no handling beyond rendering the specification section once it turns false.

The vehicle_details block

Present on /api/auction/{site}/{id} and /api/car-details. The three detail-rich sources describe the same concepts under different names — a downloadable file is Documents[] on Auto1 but ECarsTradeDocuments[] on eCarsTrade, while Documents on OpenLane is a dict of paperwork booleans and not a file list at all — so this block normalizes them. Read it instead of branching on site_name. Every key is omitted when the source has nothing for it, and the whole block is omitted while details_pending is true.

Coverage is not uniform across sources

Each auction house publishes a different subset of these keys, and the differences are large: only eCarsTrade has per-visit service rows, only Auto1 has paint measurements, OpenLane distinguishes report files from paperwork flags, KB exposes optional diagnosis and inspection records, and Japan exposes imported photos and optional sheet evidence. This is an upstream limitation, not a gap in our data — do not build a UI that assumes a key is always there. The full coverage matrix, the OpenLane report-type codes and the per-source traps live on Fields by source.

Production year, registration and trim

registration_year describes first registration; production_year uses production/model-year evidence and falls back to registration_year where absent. production_month is nullable and is not synthesized from year-only data. Use production_year_from / production_year_to and production_year_new / production_year_old for the production-year dimension. /api/production-years returns production_years and production_year_counts; /api/facets includes it as production_years. /api/types requires brand and model and returns counted trim values plus grouped model entries. Use type for trims, distinct from vehicle_type and body_style.

is_margin is a nullable VAT-scheme flag on cards and detail. True means margin, false means deductible, null means unknown. Do not interpret missing permission-gated price fields as zero. Optional source report blocks include KB kb_diagnosis and kb_inspection; Japanese imported offer evidence is under car_identification.JapanOffers.

Never exposed

Bidder and private fields — bidder identities, private bids, personal maximums, and order data — are never returned. Neither is account-scoped commercial data: the auction houses' fee, cost and delivery figures are quoted to our buyer account and our delivery address, so they describe our commercial terms rather than the vehicle.

Still served: the auction house's own published asking prices (price_buy_now, price_min_bid, price_estimation), the VAT scheme (is_margin, vat_scheme), the estimated repair cost, Specs.TransportCategoryId (a vehicle class, not a shipment), the seller/warehouse location, and buynow_tax_delivery / current_tax_delivery. For landed-cost figures use the import calculator, which is built for your own route.

Sources and enums

The European classifieds network is not in the source list. It is retail market-reference data, not auction inventory, so it is not a valid site value — see the classifieds endpoint group instead.