Describing a vehicle

This page explains how you describe a vehicle in a valuation or normalization request, how your inputs combine, and how to read the vehicle that comes back. The Vehicle object and VehicleInput are specified in the vehicles reference.

#Inputs and the returned vehicle

There are two sides:

• The input is what you send: vehicle in the request (a VehicleInput), plus any description text and images. Every field is optional apart from what is needed to identify the vehicle, and unknown values should be left out rather than guessed. You can send the attributes on this page, or an AutoUncle Vehicle Schema (AVS) vehicle document, such as the vehicle another call returned.
• The returned vehicle is the Vehicle that was identified and, for a valuation, priced: an AVS vehicle document with catalogue IDs and names for every level that could be identified, its specification, equipment, registration and odometer. Beside it, identification says how well it was identified and, in fields, where each value came from.

Always read the returned vehicle. If it is not the car you meant, the price is not for that car.

#How inputs combine

You can mix catalogue IDs, structured attributes, text and photos in one request. They are combined in this order of precedence:

1. Catalogue IDs in vehicle.catalogue (brand_id, model_id, generation_id, drivetrain_id, equipment_variant_id). They are used as given. Send any levels you know; a lower level fills in its parents, so a drivetrain_id alone identifies the brand, model and generation too. All IDs must belong to one hierarchy, or the valuation is refused with catalogue_id_conflict.
2. Structured attributes such as make, model, variant, fuel, transmission, power_hp and model_year. They are matched against the catalogue and always win over anything read from text or photos.
3. Text and photos. description is read by deterministic parsing rules and, for live keys when the deployment has it configured, by automated interpretation. Photos are used only by automated interpretation. Neither ever runs for test keys.
4. Catalogue data for the resolved drivetrain, such as fuel, power and engine size, fills attributes you did not send.
5. Defaults and assumptions, marked assumed in identification.fields and reported in warnings. Mileage is never assumed unless you set options.allow_mileage_estimation: true, and equipment never unless you set options.allow_equipment_estimation: true (see assumed equipment).

Names are matched as the catalogue spells them; common variants such as Volkswagen for the catalogue brand VW are recognized when you send them as structured make. In practice, deterministic text parsing alone often cannot identify a vehicle from a description, so with a test key (or no_ai/strict) send at least make, model, model_year and mileage as structured fields. See free text and photos.

#Identity

Every attribute on this page also has a place in an AVS vehicle document, such as identity.brand.name for make or specification.powertrain.energy for fuel; the VehicleInput table lists them.

#Mileage and units

vehicle.mileage always has a value and an explicit unit:

{
  "mileage": { "value": 45000, "unit": "km" }
}

Send the odometer reading in the unit you have; it is converted to the market's unit before scoring. The returned vehicle reports it in kilometres, as AVS vehicle.odometer.km, whatever the market. Do not convert it yourself and then send the original unit. 0 is a valid mileage. Missing mileage is refused with missing_mileage unless you opt in to the fixed 96,000 km baseline; see refusals & missing mileage.

Other units are fixed:

• power_hp is in horsepower. Convert kilowatts first (hp = kW × 1.35962, rounded), or send an AVS document with specification.powertrain.powerKw and it is converted for you.
• engine_size_l is in litres, for example 1.5. Omit it for fully electric vehicles.
• battery_kwh is the traction battery capacity in kWh.
• electric_range_km is always in kilometres, whatever the market.

#Drivetrain and specification

#Equipment

equipment is a list of feature keys from GET /v1/catalogue/enums, such as INFOTAINMENT_NAVIGATION, CAMERA_PARKING_REAR or BATTERY_HEAT_PUMP. Up to 150 keys, as strings. The earlier keys such as has_gps are still accepted. Unrecognized keys are ignored and produce an equipment_not_recognized warning.

A returned Vehicle lists its equipment as AVS features in equipment.features: { "key": "EXTERIOR_TOWBAR_FIXED", "name": "Fixed Trailer Hitch", "category": "EXTERIOR", "ids": [{ "scheme": "autouncle", "value": "f-9e2bf372ce4d984dd6722039" }], "availability": "fitted" }. The key is the most specific feature the listing or your request states (an adaptive cruise control rather than plain cruise control). A feature that is not listed is unknown, not absent. With options.allow_equipment_estimation: true, features assumed for the vehicle are listed too, with availability: "unknown" and marked assumed in identification.fields.

#Flags

flags holds boolean risk and eligibility attributes, up to 30 entries. The valuation model covers ordinary used cars for sale, so these ten flags make a vehicle ineligible, and they are the only flags with an effect:

Flags that are false change nothing. Any other flag name is ignored and the result carries a flags_not_recognized warning naming it; a market-specific flag sent for another market, such as has_yellow_plates in DE, is ignored with a flags_not_applicable warning. Each flag is also described in the request fields.

#VIN and registration plate

With a live key, a vin or registration_plate is looked up before the vehicle is resolved, and what the lookup finds fills in the attributes you left out.

The identifiers can also be sent as registration.vin and registration.registration_plate, or in an AVS document as vehicle.vin and vehicle.registration.plate. When you send both, the plate is looked up; the VIN is decoded instead only where plates cannot be looked up. Test keys never look anything up.

Your values win. A looked-up value only fills an attribute you did not send. If it disagrees with one you did send (another model, fuel, power or year), your value is used and the result carries a registry_conflict warning naming the fields; check them or the identifier. A year you send settles both model_year and first_registration. The register's odometer readings from past inspections are not the current mileage and are never used, so send vehicle.mileage as usual.

Provenance. Each looked-up value has an entry in identification.fields with source: "registry", basis: "observed" and the source_id of the source that supplied it (dk_vehicle_register, vin_decoding or de_type_approval_codes), and the source is listed in attributions. A catalogue identity matched from looked-up names is still catalogue_match, with evidence_source_id naming the source whose names it was matched from.

When a lookup cannot be used, the valuation goes ahead with the attributes you sent, and a warning says why:

If the identifier was your only description of the vehicle (no make, model, catalogue IDs, description or photos) and the lookup times out or is unavailable, the valuation fails instead, with resolution_timeout or resolution_unavailable and service: "vehicle_registry", retryable and without a charge. If it simply finds nothing, the request is refused as vehicle_not_identified.

A lookup is included in the valuation's or normalization's credit; it costs nothing extra. To look an identifier up on its own, use the vehicle lookup endpoints. It shares the processing budget. The raw VIN and plate are not stored in valuation records.

#Drive side

drive_side (left or right) is part of the contract, but in this version a request that includes it fails with 500 internal_error. Omit it until the changelog announces a fix. No credit is used when this happens.

#Valuation request fields

Every request field, generated from the OpenAPI contract:

#The returned vehicle

A valued result returns the Vehicle that was priced, with its identification beside it:

{
  "vehicle": {
    "avs": { "version": "0.3", "kind": "vehicle" },
    "identity": {
      "brand": { "name": "VW", "ids": [{ "scheme": "autouncle", "value": "b-0957579dc5bca6de229d2f32" }] },
      "model": { "name": "Golf", "ids": [{ "scheme": "autouncle", "value": "cm-6bb52590daf6d1b19108ec93" }] },
      "body": { "name": "Golf VIII", "ids": [{ "scheme": "autouncle", "value": "mg-40c5d8de40bb48ae60fc0a6c" }], "fromYear": 2019 },
      "drivetrain": { "name": "1.5 TSI (130 Hp)", "ids": [{ "scheme": "autouncle", "value": "dv-947a3199394a5a4b41cb2869" }] }
    },
    "specification": {
      "powertrain": { "energy": ["petrol"], "engine": { "displacementCc": 1500 }, "powerKw": 96, "powerHp": 130,
                      "transmission": { "type": "manual" }, "traction": "2wd" }
    },
    "vehicle": {
      "registration": { "country": "DK", "modelYear": 2021 },
      "odometer": { "km": 45000 }
    }
  },
  "identification": {
    "status": "identified",
    "level": "drivetrain",
    "catalogue_version": "5.6.9:NEW",
    "fields": {
      "/identity/brand": { "basis": "catalogue", "source": "catalogue_derived", "status": "derived" },
      "/identity/drivetrain": { "basis": "observed", "source": "catalogue_id", "status": "supplied" },
      "/specification/powertrain/powerHp": { "basis": "catalogue", "source": "catalogue_derived", "status": "derived" },
      "/vehicle/odometer": { "basis": "observed", "source": "provided", "status": "supplied" },
      "/vehicle/registration/modelYear": { "basis": "observed", "source": "provided", "status": "supplied" }
    }
  }
}

The example's fields are shortened.

• Identity. identity.brand and identity.model are always there; identity.body (AutoUncle's generation, which includes the body), identity.drivetrain and equipment.trim (the equipment variant) are present only when they were identified. Each carries its catalogue ID in ids (scheme autouncle) and its name. Store the IDs and send them back next time. A level that several catalogue records fit is left out of identity and listed in identification.candidates, and identification.status is ambiguous; the valuation still runs on the levels that are known, and a warning such as drivetrain_ambiguous tells you to pin the level.
• Specification. With an identified drivetrain, the catalogue's values; a value you sent that contradicts it has status conflict in identification.fields, with yours in supplied.
• Provenance. identification.fields, keyed by JSON Pointer into vehicle, says, per value, how it was established: source (catalogue_id, catalogue_derived, catalogue_match, provided, registry, text_parser, ai_text, ai_vision, imputed or default), basis (observed, extracted, catalogue or assumed; see field provenance basis) and status. A mileage baseline or other default has status assumed.

The matched model can be a catalogue alias of the model you named. For example, make: "Volkswagen", model: "Golf", model_year: 2020 may identify the model Golf VII (cm-88dbede1978bc412872a6e1c) rather than Golf (cm-6bb52590daf6d1b19108ec93). Both are valid catalogue IDs.

precision.identity_level names the most specific level that was identified. You can post the returned vehicle back unchanged in a later request, for example to value the same car again with a new mileage.

See the valuation result reference for every field.