Vehicles

The vehicle identification APIs: a VIN decoder, a German HSN/TSN lookup, a Danish licence plate lookup and vehicle data normalization. Every endpoint that describes a vehicle returns it the same way: vehicle is an AutoUncle Vehicle Schema (AVS) 0.3 vehicle document (which car it is, how it is built, what it is equipped with, and its registration, odometer and colour), and beside it identification says how that vehicle was identified against the AutoUncle catalogue: its status, the catalogue records that compete when the evidence cannot separate them, and where each value came from. Every request that describes a vehicle accepts the AVS document back as its vehicle (a VehicleInput), so the result of one call can be posted straight into the next.

All four vehicle endpoints need the vehicles:read scope and share the vehicle rate limit (60 requests per minute by default). A live call that finds a vehicle costs one credit; test keys, failures and calls that find nothing are free. See credits.

Note: AutoUncle Data Services is in beta. Since contract 0.9.0 the vehicle is an AVS 0.3 document; AVS itself is a draft and may still change before contract 1.0. Changes are announced in the changelog.

#The Vehicle object

vehicle is a standard AVS vehicle document, so any AVS tooling can validate and read it. Values are plain, so you can show or store them directly, and units are in the field names (powerHp, displacementCc, km).

{
  "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" }], "type": "hatchback", "fromYear": 2019 },
      "drivetrain": { "name": "1.5 TSI (130 Hp)", "ids": [{ "scheme": "autouncle", "value": "dv-947a3199394a5a4b41cb2869" }] }
    },
    "specification": {
      "body": { "type": "hatchback", "doors": 5 },
      "powertrain": { "energy": ["petrol"], "engine": { "displacementCc": 1500 }, "powerKw": 96, "powerHp": 130,
                      "transmission": { "type": "manual" }, "traction": "2wd" }
    },
    "equipment": {
      "features": [{ "key": "INFOTAINMENT_NAVIGATION", "name": "Navigation System (GPS)", "category": "INFOTAINMENT",
                     "ids": [{ "scheme": "autouncle", "value": "f-33c7d89aab7f846afc8e2613" }], "availability": "fitted" }]
    },
    "vehicle": {
      "registration": { "country": "DK", "firstRegistrationDate": "2021-03-15", "modelYear": 2021 },
      "odometer": { "km": 45000 },
      "colour": { "name": "grey" }
    }
  },
  "identification": {
    "status": "identified",
    "level": "drivetrain",
    "catalogue_version": "5.6.9:NEW",
    "fields": {
      "/identity/drivetrain": { "basis": "catalogue", "source": "catalogue_match", "status": "derived", "match_score": 1.0 },
      "/specification/powertrain/powerHp": { "basis": "catalogue", "source": "catalogue_match", "status": "confirmed" },
      "/specification/powertrain/transmission/type": { "basis": "catalogue", "source": "catalogue_match", "status": "conflict", "supplied": "automatic" },
      "/vehicle/registration/firstRegistrationDate": { "basis": "observed", "source": "provided", "status": "supplied" }
    }
  }
}

The example's fields are shortened; a real result has an entry for every value someone stated or the catalogue derived.

An AutoUncle Vehicle Schema (AVS) 0.3 vehicle document. The AVS specification describes every field.

#Reading it

• Sparse. Only avs and identity.brand and identity.model are always present. A value that is not known is left out, never sent as null, an empty object or an empty list. A missing equipment feature means unknown, not absent.
• Catalogue IDs. Each identified level carries its AutoUncle catalogue ID in ids as { "scheme": "autouncle", "value": "dv-…" }: the same ID the catalogue API returns and a request accepts. A provider's own codes never appear there.
• Generation and body. AutoUncle's generation already includes the body (a Golf VIII hatchback and a Golf VIII estate are two generations), so it is published as AVS identity.body, with its type, fromYear and toYear. Its catalogue ID is the mg-… ID that catalogue.generation_id takes.
• Equipment variant. The catalogue's equipment variant is equipment.trim, with fitted: true.
• Fuel. specification.powertrain.energy lists the energy carriers and electrification the hybrid kind, both read from the catalogue drivetrain's own fuel. electrification is left out when it is not known: the catalogue's coarse plug-in bucket also holds full hybrids, so a catalogue plug-in fuel says petrol and electricity without phev. A plug-in you or a register stated is phev.
• Units and vocabularies. engine.displacementCc is in cubic centimetres (a 1.5 litre engine is 1500), vehicle.odometer.km is always in kilometres (a reading in miles or Scandinavian miles is converted), traction is fwd, rwd, 2wd or awd (4wd is published as awd), a convertible body is cabriolet, and a pink or turquoise colour family is other.
• Doors and seats. AVS takes 1 to 6 doors and 1 to 9 seats. A larger value, such as a 12-seat minibus, is kept in the extension instead of being cut to fit.

#Extensions

extensions["com.autouncle"] holds facts AutoUncle has that AVS has no field for yet. Each key is present only when the value is known.

#Identification

identification sits beside vehicle in every result that describes one. It holds what AVS has no place for: how well the catalogue identified the vehicle, the catalogue records that compete, and per-value provenance. When the vehicle cannot be identified to a brand and a model, vehicle is left out (it would not be an AVS document) and identification says why.

#Status

level is the deepest catalogue level identified: brand, model, generation (published as identity.body) or drivetrain.

#Field provenance

identification.fields is keyed by JSON Pointer into vehicle, such as /identity/drivetrain, /specification/powertrain/powerHp, /vehicle/odometer or /equipment/features/0. Each entry says where that value came from:

How to read status:

source says what supplied the value: provided (you), registry (a register or decoder, named by source_id, which is also listed in attributions), catalogue_id, catalogue_match or catalogue_derived (the catalogue), text_parser, ai_text or ai_vision (your text or photos), imputed or default. Identity entries also carry match_score for a matched level, evidence_source_id when the level was matched from a register's or decoder's names (that source is also in attributions), and selected_by when a record was chosen among records the catalogue could not separate (ai_text: from your description; caller_evidence: from the fuel, power, drive or transmission you sent). See notes and data sources for basis.

A value with no entry was not stated by anyone. Equipment assumed with options.allow_equipment_estimation has availability: "unknown" in vehicle.equipment.features and status: "assumed" here.

#Candidates

When the generation or the drivetrain is ambiguous, identification.candidates.generation or identification.candidates.drivetrain lists up to ten catalogue records that fit what is known, closest to your power first for drivetrains. Candidates never contradict the fuel, power, drive or transmission you sent. Each item:

To settle the level, send one candidate's id back (for example as catalogue.drivetrain_id, or in identity.drivetrain.ids of an AVS document), or a fact that separates them, such as power_hp; improve_precision names the most useful one.

#VehicleInput: describing a vehicle

vehicle in a valuation or normalization request is a VehicleInput, in one of two forms:

• An AVS vehicle document, recognized by its avs member: any vehicle an endpoint returned, posted back unchanged, or one you build yourself. identification is not part of it; leave it out.
• VehicleAttributes: listing-style attributes (make, model, fuel, power_hp, catalogue IDs and so on), for integrations that only have listing data. See request fields. The groups of the Vehicle that contract versions before 0.9.0 returned (identity, specs, registration, listing, equipment) are still accepted here, so stored results of an older integration keep working.

The two forms are not mixed: a vehicle with avs is read as an AVS document only. Flags and a free-text variant have no place in AVS, so send VehicleAttributes when you need them.

Read-only parts of a returned document are accepted and ignored: avs.id, catalogue names and years next to an ID, powerKw next to powerHp, vehicle.registration.country (the request's country is the market) and vehicle.colour.family. AVS fields the valuation does not use, such as dimensions or history, are accepted and ignored too.

In VehicleAttributes, when a value in an old canonical group and a loose attribute set the same thing differently, the canonical value wins and a vehicle_input_overridden warning names the loose field. A catalogue ID wins over a name at the same level.

#Posting a result back

A lookup tells you what the car is, not what it has done since. Before you value a looked-up vehicle, replace vehicle.odometer with today's reading, without readAt. A register's reading is from the last periodic inspection, dated by readAt; posted back unchanged it is ignored (dated_mileage_ignored), so the valuation is refused for missing mileage unless you send today's reading.

curl https://data-services.autouncle.com/v1/valuations \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: valuation-vehicle-001' \
  -d @- <<'JSON'
{
  "country": "DK",
  "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"
          }
        ],
        "type": "hatchback"
      },
      "drivetrain": {
        "name": "1.5 TSI (130 Hp)",
        "ids": [
          {
            "scheme": "autouncle",
            "value": "dv-947a3199394a5a4b41cb2869"
          }
        ]
      }
    },
    "specification": {
      "powertrain": {
        "energy": [
          "petrol"
        ],
        "powerHp": 130,
        "powerKw": 96,
        "transmission": {
          "type": "manual"
        }
      }
    },
    "vehicle": {
      "registration": {
        "country": "DK",
        "firstRegistrationDate": "2021-03-15",
        "modelYear": 2021
      },
      "odometer": {
        "km": 45000
      }
    }
  }
}
JSON

require "json"
require "net/http"

uri = URI("https://data-services.autouncle.com/v1/valuations")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "valuation-vehicle-001"
request.body = JSON.generate({
  "country" => "DK",
  "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"
          }
        ],
        "type" => "hatchback"
      },
      "drivetrain" => {
        "name" => "1.5 TSI (130 Hp)",
        "ids" => [
          {
            "scheme" => "autouncle",
            "value" => "dv-947a3199394a5a4b41cb2869"
          }
        ]
      }
    },
    "specification" => {
      "powertrain" => {
        "energy" => [
          "petrol"
        ],
        "powerHp" => 130,
        "powerKw" => 96,
        "transmission" => {
          "type" => "manual"
        }
      }
    },
    "vehicle" => {
      "registration" => {
        "country" => "DK",
        "firstRegistrationDate" => "2021-03-15",
        "modelYear" => 2021
      },
      "odometer" => {
        "km" => 45000
      }
    }
  }
})
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.pretty_generate(JSON.parse(response.body))

import json
import os

import requests

response = requests.post(
    "https://data-services.autouncle.com/v1/valuations",
    headers={
        "Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
        "Idempotency-Key": "valuation-vehicle-001",
    },
    json={
        "country": "DK",
        "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"
                        }
                    ],
                    "type": "hatchback"
                },
                "drivetrain": {
                    "name": "1.5 TSI (130 Hp)",
                    "ids": [
                        {
                            "scheme": "autouncle",
                            "value": "dv-947a3199394a5a4b41cb2869"
                        }
                    ]
                }
            },
            "specification": {
                "powertrain": {
                    "energy": [
                        "petrol"
                    ],
                    "powerHp": 130,
                    "powerKw": 96,
                    "transmission": {
                        "type": "manual"
                    }
                }
            },
            "vehicle": {
                "registration": {
                    "country": "DK",
                    "firstRegistrationDate": "2021-03-15",
                    "modelYear": 2021
                },
                "odometer": {
                    "km": 45000
                }
            }
        }
    },
    timeout=30,
)
print(json.dumps(response.json(), indent=2))

const response = await fetch("https://data-services.autouncle.com/v1/valuations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "valuation-vehicle-001",
  },
  body: JSON.stringify({
    country: "DK",
    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"
            }
          ],
          type: "hatchback"
        },
        drivetrain: {
          name: "1.5 TSI (130 Hp)",
          ids: [
            {
              scheme: "autouncle",
              value: "dv-947a3199394a5a4b41cb2869"
            }
          ]
        }
      },
      specification: {
        powertrain: {
          energy: [
            "petrol"
          ],
          powerHp: 130,
          powerKw: 96,
          transmission: {
            type: "manual"
          }
        }
      },
      vehicle: {
        registration: {
          country: "DK",
          firstRegistrationDate: "2021-03-15",
          modelYear: 2021
        },
        odometer: {
          km: 45000
        }
      }
    }
  }),
});
console.log(JSON.stringify(await response.json(), null, 2));

#How a vehicle is identified

Every endpoint runs the same identification, so a vehicle identifies the same way whether you normalize it, look it up or value it:

1. Identifiers are looked up. A VIN, plate or HSN/TSN pair goes to the source for the market: the Danish Motor Register for plates and VINs in DK, VIN decoding elsewhere, the KBA type snapshot for HSN/TSN. Nothing is looked up in DE, IT or ES on a valuation's or normalization's behalf, and test keys never call a source.
2. The source's answer is mapped to the public vocabulary (fuel, body, gearbox, colour). A label without a public equivalent is left out rather than guessed. Looked-up values only fill what you left out; a value that disagrees with yours gives a registry_conflict warning and yours is used.
3. The facts are matched against the catalogue: catalogue IDs first, then names, specs, your text and, where configured, automated interpretation of text and photos. A drivetrain is chosen only when the evidence names one; otherwise identity stops at the generation, or the competing records become candidates.
4. The vehicle is published as an AVS document with the catalogue's values where the drivetrain is known and your or the source's values elsewhere, and identification gives the status, candidates and provenance for every value.

A lookup's status reports what the source said; identification.status reports how well the catalogue identified it. A register that knows the car but names a make the catalogue does not know gives status: resolved and identification.status: unidentified, with the register's names in vehicle.identity and its values in specification and vehicle.

#POST /v1/vehicles/normalize

Resolve a vehicle without valuing it.

Identifies a vehicle against the AutoUncle catalogue without valuing it. Send a VehicleInput (catalogue IDs, names, specs, identifiers, or a Vehicle another endpoint returned), a description or images, the same as a valuation accepts, and get back the Vehicle: catalogue identity, specs, equipment, registration and listing, with provenance per field. A VIN or plate in the vehicle is looked up as for a valuation. When several catalogue records fit, the ambiguous level is left out of identity and the records are returned as candidates. One credit per successful live normalization; refusals, failures, idempotent replays and test keys are free. Needs the vehicles:read scope and counts against the vehicle rate limit; it shares the valuation concurrency limits. Retry an unknown network outcome with the same Idempotency-Key: a replay identifies the same input again without spending a credit.

• Scope: vehicles:read
• Cost: One credit for a successful (normalized) live normalization, plus one when sent photos were used. Test keys, refusals, failures and idempotent replays are free.
• Rate limit: vehicles bucket, default 60 requests per minute, counted separately from valuations. See limits.

#Parameters

#Request body

application/json, a NormalizationRequest: A normalization request for one market. It accepts the same vehicle (a VehicleInput, including a Vehicle returned by any endpoint), description and images as a valuation request. Nothing is valued and no year or mileage is assumed. Unknown fields are rejected.

Structured example:

{
  "country": "DK",
  "vehicle": {
    "make": "Volkswagen",
    "model": "Golf",
    "model_year": 2019,
    "fuel": "diesel",
    "transmission": "automatic"
  }
}

Text example:

{
  "country": "DK",
  "description": "VW Golf 2.0 TDI DSG Highline, 2019, 84.000 km"
}

Canonical example:

{
  "country": "DK",
  "vehicle": {
    "identity": {
      "brand": {
        "name": "Volkswagen"
      },
      "model": {
        "name": "Golf"
      }
    },
    "specs": {
      "energy": {
        "fuel": "diesel"
      },
      "power": {
        "kw": 110
      },
      "transmission": {
        "type": "automatic"
      }
    },
    "registration": {
      "first_registration": "2019-05-14"
    },
    "listing": {
      "mileage": {
        "value": 84000,
        "unit": "km"
      }
    }
  }
}

#Response

application/json, a NormalizationResponse: A normalized vehicle with its provenance, any candidates, hints, warnings, usage and the common notes and attributions. Errors return a Problem as application/problem+json.

#Response headers

#Errors

#Examples

curl https://data-services.autouncle.com/v1/vehicles/normalize \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: normalization-001' \
  -d @- <<'JSON'
{
  "country": "DK",
  "vehicle": {
    "make": "Volkswagen",
    "model": "Golf",
    "model_year": 2019,
    "fuel": "diesel",
    "transmission": "automatic"
  }
}
JSON

require "json"
require "net/http"

uri = URI("https://data-services.autouncle.com/v1/vehicles/normalize")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "normalization-001"
request.body = JSON.generate({
  "country" => "DK",
  "vehicle" => {
    "make" => "Volkswagen",
    "model" => "Golf",
    "model_year" => 2019,
    "fuel" => "diesel",
    "transmission" => "automatic"
  }
})
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.pretty_generate(JSON.parse(response.body))

import json
import os

import requests

response = requests.post(
    "https://data-services.autouncle.com/v1/vehicles/normalize",
    headers={
        "Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
        "Idempotency-Key": "normalization-001",
    },
    json={
        "country": "DK",
        "vehicle": {
            "make": "Volkswagen",
            "model": "Golf",
            "model_year": 2019,
            "fuel": "diesel",
            "transmission": "automatic"
        }
    },
    timeout=30,
)
print(json.dumps(response.json(), indent=2))

const response = await fetch("https://data-services.autouncle.com/v1/vehicles/normalize", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "normalization-001",
  },
  body: JSON.stringify({
    country: "DK",
    vehicle: {
      make: "Volkswagen",
      model: "Golf",
      model_year: 2019,
      fuel: "diesel",
      transmission: "automatic"
    }
  }),
});
console.log(JSON.stringify(await response.json(), null, 2));

#The normalization result

Normalization identifies a vehicle the way a valuation would, without valuing it. It never assumes a year or mileage and nothing is scored. The body accepts the same country, vehicle, description and images as a valuation request, options.resolution and options.allow_equipment_estimation (assumed equipment); it has no pricing and none of the valuation-only options. The response's top-level ambiguous is true exactly when identification.status is ambiguous.

{
  "request_id": "nrm_3f1c0e7a9b2d4c6e8f0a1b2c3d4e5f60",
  "object": "normalization",
  "status": "normalized",
  "country": "DK",
  "mode": "test",
  "ambiguous": true,
  "vehicle": {
    "avs": { "version": "0.3", "kind": "vehicle" },
    "identity": {
      "brand": { "name": "VW", "ids": [{ "scheme": "autouncle", "value": "b-0957579dc5bca6de229d2f32" }] },
      "model": { "name": "Golf VII", "ids": [{ "scheme": "autouncle", "value": "cm-88dbede1978bc412872a6e1c" }] },
      "body": { "name": "Golf VII (5-door, facelift 2017)", "ids": [{ "scheme": "autouncle", "value": "mg-43ed101760c6bc4c4c2e44bd" }],
                "type": "hatchback", "fromYear": 2017, "toYear": 2021 }
    },
    "specification": {
      "body": { "type": "hatchback" },
      "powertrain": { "energy": ["diesel"], "transmission": { "type": "automatic" } }
    },
    "vehicle": { "registration": { "country": "DK", "modelYear": 2019 } }
  },
  "identification": {
    "status": "ambiguous",
    "level": "generation",
    "catalogue_version": "5.6.9:NEW",
    "candidates": {
      "drivetrain": [
        { "id": "dv-7cf0fd34ad595be222c8d868", "name": "1.6 TDI (115 Hp) DSG", "score": 0.999999, "mismatches": [],
          "specs": { "energy": { "fuel": "diesel" }, "power": { "hp": 115 }, "engine_size_l": 1.6, "transmission": { "type": "automatic" }, "traction": "2wd", "doors": 5 } },
        { "id": "dv-19bb09bae7bda50662f935ea", "name": "2.0 TDI (150 Hp) DSG", "score": 0.999999, "mismatches": [],
          "specs": { "energy": { "fuel": "diesel" }, "power": { "hp": 150 }, "engine_size_l": 2.0, "transmission": { "type": "automatic" }, "traction": "2wd", "doors": 5 } }
      ]
    },
    "fields": {
      "/identity/body": { "basis": "catalogue", "source": "catalogue_match", "status": "derived", "match_score": 1.0 },
      "/identity/brand": { "basis": "catalogue", "source": "catalogue_match", "status": "derived", "match_score": 1.0 },
      "/identity/drivetrain": { "basis": "catalogue", "source": "catalogue_match", "status": "ambiguous", "candidate_count": 5 },
      "/identity/model": { "basis": "catalogue", "source": "catalogue_match", "status": "derived", "match_score": 1.0 },
      "/specification/body/type": { "basis": "catalogue", "source": "catalogue_derived", "status": "derived" },
      "/specification/powertrain/energy": { "basis": "observed", "source": "provided", "status": "supplied" },
      "/specification/powertrain/transmission/type": { "basis": "observed", "source": "provided", "status": "supplied" },
      "/vehicle/registration/modelYear": { "basis": "observed", "source": "provided", "status": "supplied" }
    }
  },
  "improve_precision": [
    { "field": "vehicle.catalogue.drivetrain_id", "reason": "drivetrain_ambiguous", "expected_impact": "high",
      "message": "Several drivetrains fit equally well. Provide power_hp, battery_kwh or engine_size_l, or select the drivetrain from the catalogue." }
  ],
  "warnings": [
    { "code": "drivetrain_ambiguous", "message": "More than one drivetrain fits the supplied information. Select its catalogue ID for greater precision." }
  ],
  "usage": { "billable": false, "credits_used": 0, "original_credits_used": 0, "credits_remaining": 0, "cache_hit": false, "idempotent_replay": false, "mode": "test" },
  "notes": [],
  "attributions": [{ "source_id": "autouncle_vehicle_catalogue", "...": "see notes and data sources" }]
}

The example is shortened to two of the five candidates. The ambiguous drivetrain is left out of vehicle.identity and appears in identification.fields without a value.

A successful live normalization uses one credit. Test keys, refusals, failures and idempotent replays are free; test keys are not simulated, only free. Normalizations appear in the console request log with a nrm_… ID; they are not valuations, so GET /v1/valuations/{id} does not return them. Retry an unknown network outcome with the same Idempotency-Key and body: a replay identifies the input again without spending a credit.

#Vehicle lookups

A lookup turns an identifier into a vehicle. What the source says is identified against the catalogue like any other evidence, so the result carries catalogue IDs you can send to the catalogue or post back to a valuation.

• A VIN identifies the brand and usually the model and model year. It does not identify the exact engine or trim, so a decoded vehicle rarely gets past the model or generation. It never yields German HSN/TSN codes.
• HSN/TSN gives brand and model names only. The Kraftfahrt-Bundesamt type rows carry no technical data, and they are a dated snapshot that does not cover every historical type.
• A Danish plate gives the register's record: make, model, variant, VIN, first registration, power, fuel, gearbox, body, doors, colour and the last inspection's odometer reading. That is usually enough for a drivetrain.
• no_match is an answer, not an error. The input was valid and the source does not know it. A failed lookup returns an error (lookup_unavailable or lookup_timeout); never treat it as "not found".
• Test keys get a fixed synthetic record (a 2021 Volkswagen Golf) with synthetic: true and a synthetic_example note, without looking the input up. Its catalogue identification is real.
• Nothing is stored. AutoUncle keeps the request log entry (lkp_… ID, status, timing, credits) but not the VIN, plate or codes, so a lookup cannot be read back. Retrying is a new lookup.

#POST /v1/vehicles/decode

Decode a VIN into an AutoUncle vehicle.

Decodes a 17-character VIN and identifies what the decoder says against the AutoUncle catalogue. The result is the same Vehicle valuations and normalizations return, with catalogue identity, provenance per field, candidates, improvement hints, notes and source attributions; post it back as the vehicle of a valuation. One credit per live lookup that returns vehicle data (resolved, suggested or ambiguous); no_match, failures and test keys are free. A VIN never yields German HSN/TSN codes; use POST /v1/vehicles/hsn-tsn with codes from the registration document. Test keys return a fixed synthetic record without decoding; its catalogue identification is real.

• Scope: vehicles:read
• Cost: One credit for a live lookup that returns vehicle data (resolved, suggested or ambiguous). no_match, failures and test keys are free.
• Rate limit: vehicles bucket, default 60 requests per minute, counted separately from valuations. See limits.

#Request body

application/json, a VinDecodeRequest: A VIN to decode. Unknown fields are rejected.

Vin example:

{
  "vin": "WVWZZZ1KZ5P000001",
  "country": "DE"
}

#Response

application/json, a VehicleLookupResult: The vehicle a lookup found, identified against the catalogue, with provenance, improvement hints, warnings, notes, attributions and billing. Errors return a Problem as application/problem+json.

#Response headers

#Errors

#Examples

curl https://data-services.autouncle.com/v1/vehicles/decode \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d @- <<'JSON'
{
  "vin": "WVWZZZ1KZ5P000001",
  "country": "DE"
}
JSON

require "json"
require "net/http"

uri = URI("https://data-services.autouncle.com/v1/vehicles/decode")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "vin" => "WVWZZZ1KZ5P000001",
  "country" => "DE"
})
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.pretty_generate(JSON.parse(response.body))

import json
import os

import requests

response = requests.post(
    "https://data-services.autouncle.com/v1/vehicles/decode",
    headers={
        "Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
    },
    json={
        "vin": "WVWZZZ1KZ5P000001",
        "country": "DE"
    },
    timeout=30,
)
print(json.dumps(response.json(), indent=2))

const response = await fetch("https://data-services.autouncle.com/v1/vehicles/decode", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    vin: "WVWZZZ1KZ5P000001",
    country: "DE"
  }),
});
console.log(JSON.stringify(await response.json(), null, 2));

#Example VIN response

{
  "object": "vehicle_lookup",
  "request_id": "lkp_6f1d0c2e9a8b47d3b5e1c0a9f2d4e6b8",
  "lookup": "vin",
  "status": "resolved",
  "country": "DE",
  "mode": "live",
  "synthetic": false,
  "vehicle": {
    "avs": { "version": "0.3", "kind": "vehicle" },
    "identity": {
      "brand": { "name": "VW", "ids": [{ "scheme": "autouncle", "value": "b-0957579dc5bca6de229d2f32" }] },
      "model": { "name": "Golf VII", "ids": [{ "scheme": "autouncle", "value": "cm-88dbede1978bc412872a6e1c" }] }
    },
    "vehicle": {
      "vin": "WVWZZZAUZKW000001",
      "registration": { "country": "DE", "modelYear": 2019 }
    }
  },
  "identification": {
    "status": "partially_identified",
    "level": "model",
    "catalogue_version": "5.6.9:NEW",
    "fields": {
      "/identity/brand": { "basis": "catalogue", "source": "catalogue_match", "evidence_source_id": "vin_decoding", "status": "derived", "match_score": 1.0 },
      "/identity/model": { "basis": "catalogue", "source": "catalogue_match", "evidence_source_id": "vin_decoding", "status": "derived", "match_score": 1.0 },
      "/vehicle/registration/modelYear": { "basis": "observed", "source": "registry", "source_id": "vin_decoding", "status": "supplied" },
      "/vehicle/vin": { "basis": "observed", "source": "provided", "status": "supplied" }
    }
  },
  "freshness": { "retrieved_at": "2026-11-01T10:00:00Z", "cached": false, "data_as_of": null, "dataset_version": "orvin 0.3.1 / dataset 2026.09.25.2" },
  "improve_precision": [
    { "field": "vehicle.catalogue.drivetrain_id", "reason": "drivetrain_unresolved", "expected_impact": "high",
      "message": "Select the exact engine and transmission from the catalogue." }
  ],
  "warnings": [],
  "notes": [],
  "attributions": [
    { "source_id": "vin_decoding", "name": "VIN decoding", "...": "licence and attribution text" },
    { "source_id": "autouncle_vehicle_catalogue", "...": "see notes and data sources" }
  ],
  "usage": { "billable": true, "credits_used": 1, "original_credits_used": 1, "credits_remaining": 29, "cache_hit": false, "idempotent_replay": false, "mode": "live" }
}

The example's hint and attributions are shortened; a real response lists every source behind a published value.

#POST /v1/vehicles/hsn-tsn

Look up German HSN/TSN type codes.

Looks up the German manufacturer and type codes from a Zulassungsbescheinigung (HSN, field 2.1, and the first three characters of TSN, field 2.2) in the Kraftfahrt-Bundesamt type snapshot and identifies the brand and model names it gives against the AutoUncle catalogue. KBA type rows carry no technical data, so the vehicle rarely gets past the model. One credit per live lookup that returns vehicle data; no_match, failures and test keys are free.

• Scope: vehicles:read
• Cost: One credit for a live lookup that returns vehicle data (resolved, suggested or ambiguous). no_match, failures and test keys are free.
• Rate limit: vehicles bucket, default 60 requests per minute, counted separately from valuations. See limits.

#Request body

application/json, a HsnTsnRequest: German type codes to look up. Unknown fields are rejected.

Hsn tsn example:

{
  "hsn": "0603",
  "tsn": "BMT"
}

#Response

application/json, a VehicleLookupResult: The vehicle a lookup found, identified against the catalogue, with provenance, improvement hints, warnings, notes, attributions and billing. Errors return a Problem as application/problem+json.

#Response headers

#Errors

#Examples

curl https://data-services.autouncle.com/v1/vehicles/hsn-tsn \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d @- <<'JSON'
{
  "hsn": "0603",
  "tsn": "BMT"
}
JSON

require "json"
require "net/http"

uri = URI("https://data-services.autouncle.com/v1/vehicles/hsn-tsn")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "hsn" => "0603",
  "tsn" => "BMT"
})
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.pretty_generate(JSON.parse(response.body))

import json
import os

import requests

response = requests.post(
    "https://data-services.autouncle.com/v1/vehicles/hsn-tsn",
    headers={
        "Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
    },
    json={
        "hsn": "0603",
        "tsn": "BMT"
    },
    timeout=30,
)
print(json.dumps(response.json(), indent=2))

const response = await fetch("https://data-services.autouncle.com/v1/vehicles/hsn-tsn", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    hsn: "0603",
    tsn: "BMT"
  }),
});
console.log(JSON.stringify(await response.json(), null, 2));

#Example HSN/TSN response

{
  "object": "vehicle_lookup",
  "lookup": "hsn_tsn",
  "status": "resolved",
  "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" }] }
    },
    "vehicle": { "registration": { "country": "DE" } },
    "extensions": { "com.autouncle": { "hsn": "0603", "tsn": "BMT" } }
  },
  "identification": {
    "status": "partially_identified",
    "level": "model",
    "catalogue_version": "5.6.9:NEW",
    "fields": {
      "/extensions/com.autouncle/hsn": { "basis": "observed", "source": "provided", "status": "supplied" },
      "/extensions/com.autouncle/tsn": { "basis": "observed", "source": "provided", "status": "supplied" },
      "/identity/brand": { "basis": "catalogue", "source": "catalogue_match", "evidence_source_id": "de_type_approval_codes", "status": "derived", "match_score": 1.0 },
      "/identity/model": { "basis": "catalogue", "source": "catalogue_match", "evidence_source_id": "de_type_approval_codes", "status": "derived", "match_score": 0.92 }
    }
  }
}

The example shows only the vehicle and its identification; the envelope is the same as for a VIN. Its attributions list de_type_approval_codes, the Kraftfahrt-Bundesamt vehicle type data (HSN/TSN), published under the Data licence Germany – attribution – version 2.0 (dl-de/by-2-0): show its attribution text with the data.

#POST /v1/vehicles/lookup

Look up a vehicle by registration plate.

Looks the plate up in the country's vehicle register and identifies the registered vehicle against the AutoUncle catalogue. Denmark (DK) only in this version, through the Danish Motor Register (DMR); other countries return lookup_country_unsupported before anything is reserved. One credit per live lookup that finds the vehicle; no_match, failures and test-key lookups are free. Send the plate only in the JSON body. The plate and the register's answer are never stored; the request log keeps the outcome only.

• Scope: vehicles:read
• Cost: One credit for a live lookup that finds the vehicle. no_match, failures, unsupported countries and test keys are free.
• Rate limit: vehicles bucket, default 60 requests per minute, counted separately from valuations. See limits.

#Request body

application/json, a PlateLookupRequest: A registration-plate lookup. Unknown fields are rejected.

#Response

application/json, a VehicleLookupResult: The vehicle a lookup found, identified against the catalogue, with provenance, improvement hints, warnings, notes, attributions and billing. Errors return a Problem as application/problem+json.

#Response headers

#Errors

#Examples

curl https://data-services.autouncle.com/v1/vehicles/lookup \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d @- <<'JSON'
{
  "country": "DK",
  "plate": "AB12345"
}
JSON

require "json"
require "net/http"

uri = URI("https://data-services.autouncle.com/v1/vehicles/lookup")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "country" => "DK",
  "plate" => "AB12345"
})
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.pretty_generate(JSON.parse(response.body))

import json
import os

import requests

response = requests.post(
    "https://data-services.autouncle.com/v1/vehicles/lookup",
    headers={
        "Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
    },
    json={
        "country": "DK",
        "plate": "AB12345"
    },
    timeout=30,
)
print(json.dumps(response.json(), indent=2))

const response = await fetch("https://data-services.autouncle.com/v1/vehicles/lookup", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    country: "DK",
    plate: "AB12345"
  }),
});
console.log(JSON.stringify(await response.json(), null, 2));

#Plates and privacy

Denmark (DK) is the only country in this version, through the Danish Motor Register (DMR). Other countries return lookup_country_unsupported before anything is reserved, with reason no_registry when no register is connected yet, or excluded_by_policy where registry lookups are not offered.

• Send the plate only in the JSON body, never in a URL or query string.
• The plate and the register's answer are not stored. The request log keeps the lkp_… ID, market, outcome and credits.
• The register's answer never includes owner, insurance, lien or tax data.
• Register labels with a public equivalent (fuel, body, gearbox, colour) are mapped; a label without one is left out rather than guessed.
• vehicle.vehicle.odometer is the odometer reading at the last periodic inspection, dated by readAt. It is not today's mileage.
• Look up plates only for a purpose you can justify, such as a vehicle a customer asked you to check.

#Example plate response

{
  "object": "vehicle_lookup",
  "request_id": "lkp_0b5e8f2a4c6d4e1f9a7b3c5d2e8f1a6b",
  "lookup": "plate",
  "status": "resolved",
  "country": "DK",
  "mode": "live",
  "synthetic": false,
  "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" }], "type": "hatchback", "fromYear": 2019 },
      "drivetrain": { "name": "1.5 TSI (130 Hp)", "ids": [{ "scheme": "autouncle", "value": "dv-947a3199394a5a4b41cb2869" }] }
    },
    "specification": {
      "body": { "type": "hatchback", "doors": 5 },
      "powertrain": { "energy": ["petrol"], "engine": { "displacementCc": 1500 }, "powerKw": 96, "powerHp": 130,
                      "transmission": { "type": "manual" }, "traction": "2wd" }
    },
    "vehicle": {
      "registration": { "plate": "AB12345", "country": "DK", "firstRegistrationDate": "2021-03-15", "modelYear": 2021 },
      "odometer": { "km": 38000, "readAt": "2025-03-02" },
      "colour": { "name": "Grå" }
    }
  },
  "identification": {
    "status": "identified",
    "level": "drivetrain",
    "catalogue_version": "5.6.9:NEW",
    "fields": {
      "/identity/drivetrain": { "basis": "catalogue", "source": "catalogue_match", "status": "derived", "match_score": 1.0 },
      "/specification/powertrain/powerHp": { "basis": "catalogue", "source": "catalogue_match", "status": "confirmed" },
      "/vehicle/odometer": { "basis": "observed", "source": "registry", "source_id": "dk_vehicle_register", "status": "supplied" },
      "/vehicle/registration/firstRegistrationDate": { "basis": "observed", "source": "registry", "source_id": "dk_vehicle_register", "status": "supplied" },
      "/vehicle/registration/plate": { "basis": "observed", "source": "provided", "status": "supplied" }
    }
  },
  "freshness": { "retrieved_at": "2026-11-01T15:04:05Z", "cached": false, "data_as_of": null, "dataset_version": null },
  "improve_precision": [],
  "warnings": [],
  "notes": [],
  "attributions": [
    { "source_id": "dk_vehicle_register", "name": "Danish Motor Register (DMR)", "url": null, "party": "third_party", "role": "vehicle_registry", "license": null, "attribution_text": null, "notice_status": "pending_review", "notice_version": "dk_vehicle_register@2", "...": "pointers to the values it supplied" },
    { "source_id": "autouncle_vehicle_catalogue", "...": "see notes and data sources" }
  ],
  "usage": { "billable": true, "credits_used": 1, "original_credits_used": 1, "credits_remaining": 29, "cache_hit": false, "idempotent_replay": false, "mode": "live" }
}

The example's fields and attributions are shortened; a real response lists every value.

#The lookup result

The three lookup endpoints return the same envelope, listed field by field under each endpoint above. Read two statuses:

• status is the source's answer: resolved (it returned vehicle data), suggested (only conditional answers; read the notes), ambiguous (the source holds competing answers), no_match (a valid input it does not know), or unsupported and invalid_input (it could not answer this input). Only the first three are billed. Test keys always get resolved.
• identification.status is how well the catalogue identified what the source said.

improve_precision and warnings work as for valuations: a hint names the request field that would identify the vehicle more precisely, and a warning such as registry_no_match or model_not_recognized says what could not be used.

#Freshness

#Attributions

Every source behind a published value is listed in attributions, with the publisher's own licence and attribution text, as the source publishes it. Show attribution_text wherever you show or store the data, and never shorten it. Sources that did not contribute a published value are not listed. See notes and attributions.