Decoding VINs with the free NHTSA vPIC API: a practical guide

Your first request to the NHTSA VIN decoder API

No key, no sign-up. A plain GET works from a terminal:

curl "https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVinValues/\1HGCM82633A004352?format=json&modelyear=2003"

The answer has four top-level keys: Count, Message, SearchCriteria and Results, an array with one object per VIN. Trimmed to the fields most people use, the result for this 2003 Honda Accord looks like this:

{  "Count": 1,  "Message": "Results returned successfully. NOTE: Any missing ...",  "SearchCriteria": "VIN(s): 1HGCM82633A004352",  "Results": [{    "Make": "HONDA",    "Manufacturer": "AMERICAN HONDA MOTOR CO., INC.",    "Model": "Accord",    "ModelYear": "2003",    "Trim": "EX-V6",    "BodyClass": "Coupe",    "VehicleType": "PASSENGER CAR",    "DriveType": "",    "FuelTypePrimary": "Gasoline",    "EngineCylinders": "6",    "DisplacementL": "2.998832712",    "EngineHP": "240",    "TransmissionStyle": "Automatic",    "PlantCity": "MARYSVILLE",    "PlantCountry": "UNITED STATES (USA)",    "VehicleDescriptor": "1HGCM826*3A",    "ErrorCode": "0",    "ErrorText": "0 - VIN decoded clean. Check Digit (9th ...",    "SuggestedVIN": ""  }]}

Three things to notice. Every value is a string, including ModelYear and EngineCylinders, so parse numbers yourself. Missing data is an empty string, and the Message spells out what that means: NHTSA has no data for that variable, which is different from "the car does not have it". And some fields carry Not Applicable (for example BedType on a coupe), which is again different from empty. The DriveType of this Accord is empty although the car obviously drives its front wheels.

The vPIC endpoints worth knowing

The API page↗ lists more than twenty calls. All accept format=json, xml or csv; JSON is what you want. The ones that matter for VIN work:

The make and model lists are useful for dropdowns, but they are large and full of entries that never appear on a road (trailer makers, small coachbuilders). GetModelsForMakeYear with a vehicle type is the practical way to build a make, year, model picker.

GetVehicleVariableValuesList deserves a mention because it gives you the full vocabulary before you write a mapping: 71 body classes, from Sedan/Saloon to Incomplete - Chassis Cab (Single Cab), 23 drive types and 14 primary fuel types at the time of writing. Map from that list, not from the handful of values you happened to see in testing.

Reading ErrorCode and ErrorText

ErrorCode is not a number but a string that can hold several codes separated by commas, such as "1,8,400". ErrorText repeats them with descriptions, separated by semicolons, and AdditionalErrorText sometimes names the exact problem (Invalid character(s): 9:D.). Split the code string and decide per code:

The important point is that an error code does not mean an empty answer. Change one character of the Accord's VIN so the check digit fails, and vPIC still returns Honda, Accord, Coupe and six cylinders, now with error 1. Whether to keep that data is your decision, and it should depend on where the VIN came from: a typed VIN from a user deserves a second look, a VIN read from an auction lot of a European car does not.

Sending modelyear matters more than it seems. The model year code in position 10 repeats every 30 years, and NHTSA's documentation recommends always sending the year so the decoder looks in the right range. In our tests a made-up Kia VIN without the parameter decoded to 1993; with modelyear=2023 it decoded to 2023 and added error 12. If you know the year from the registration or the listing, send it.

Partial VINs and the asterisk

vPIC also decodes VINs shorter than 17 characters, with * standing for the characters you do not have. 1HGCM826*3A (the first 11 characters with the check digit replaced) returns Honda, Accord, 2003, Coupe and six cylinders, with error 6, incomplete VIN. That is useful when an old document or a photo shows only part of the VIN, or when you want the specification of a model line without a real car. The VehicleDescriptor field in every answer is exactly this pattern for the VIN you sent.

Which fields are reliable and which are often empty

vPIC holds what manufacturers file with NHTSA, and they file the identity of the vehicle carefully and the details less so. From the auction VINs we decode, this is how we would rank the fields we use:

A few gotchas when you map these values into your own fields:

• `4x2` is not a drive type you can map. It says two wheels are driven, not which two. Leave front or rear empty unless another source tells you.
• Hybrids report their engine fuel first. A Prius decodes with FuelTypePrimary Gasoline, FuelTypeSecondary Electric and ElectrificationLevel Strong HEV. Read all three before you label a car.
• Body classes are combined labels. Hatchback/Liftback/Notchback covers three body styles; Sedan/Saloon is one. Map from the full list of values.
• `Make` is upper case and `Model` is not. Normalise case before you match against your own catalogue.
• Displacement is not rounded. 2.998832712 is a 3.0-litre engine; round for display, keep the raw value.

Decoding a VIN in JavaScript and Python

A single decode in JavaScript (Node 18 or later), with a timeout, the error codes split, and empty or Not Applicable values turned into null:

const VPIC = 'https://vpic.nhtsa.dot.gov/api/vehicles'const EMPTY = new Set(['', 'Not Applicable']) function clean(value) {  if (typeof value !== 'string') return null  const v = value.trim()  return EMPTY.has(v) ? null : v} async function decodeVin(vin, modelYear) {  const url = new URL(`${VPIC}/DecodeVinValues/${encodeURIComponent(vin)}`)  url.searchParams.set('format', 'json')  if (modelYear) url.searchParams.set('modelyear', String(modelYear))  const res = await fetch(url, { signal: AbortSignal.timeout(10000) })  if (!res.ok) throw new Error(`vPIC HTTP ${res.status}`)  const body = await res.json()  const row = Array.isArray(body?.Results) ? body.Results[0] : null  if (!row || typeof row !== 'object') return null  const codes = String(row.ErrorCode ?? '')    .split(',').map(c => c.trim()).filter(Boolean)  const year = Number(clean(row.ModelYear))  const cylinders = Number(clean(row.EngineCylinders))  return {    codes,    make: clean(row.Make),    model: clean(row.Model),    year: Number.isInteger(year) && year > 0 ? year : null,    bodyClass: clean(row.BodyClass),    vehicleType: clean(row.VehicleType),    driveType: clean(row.DriveType),    fuel: clean(row.FuelTypePrimary) ?? clean(row.FuelTypeSecondary),    cylinders: cylinders > 0 ? cylinders : null  }}

The batch call takes a POST with two form fields: format=json and DATA, a string of VINs separated by semicolons, each optionally followed by a comma and its model year. The limit is 50 VINs per request, and the results come back in the same flat shape as DecodeVinValues. In Python with requests:

import requests VPIC = 'https://vpic.nhtsa.dot.gov/api/vehicles'  def decode_batch(items):    """items: list of (vin, model_year or None), at most 50."""    if not 0 < len(items) <= 50:        raise ValueError('vPIC batch takes 1 to 50 VINs')    data = ';'.join(f'{v},{y}' if y else v for v, y in items)    res = requests.post(        f'{VPIC}/DecodeVINValuesBatch/',        data={'format': 'json', 'DATA': data},        timeout=(10, 60),    )    res.raise_for_status()    rows = res.json().get('Results') or []    return {r.get('VIN'): r for r in rows if isinstance(r, dict)}  result = decode_batch([('1HGCM82633A004352', 2003),                       ('YV1MC67278J058366', None)])print(result['YV1MC67278J058366'].get('BodyClass'))# Convertible/Cabriolet

Rate limits, caching and being a good citizen

NHTSA does not publish a number of requests per minute. The documentation says only that automated traffic is subject to a rate control mechanism to protect the service. In practice that means: use the batch call instead of 50 single calls, keep concurrency low (one or two requests in flight), set timeouts, and back off on errors and timeouts rather than retrying at once. While writing this guide the service answered 503 for a while after a burst of test requests, so treat 5xx answers and timeouts as temporary and make the decode step retryable later. Do not decode the same VIN twice.

Caching is easy because a VIN's decoded data hardly ever changes. The response itself comes with cache-control: no-cache, so the caching is up to you:

• Store the raw Results row per VIN (and model year, if you sent one) in your own table, with the date of the decode.
• Serve repeated lookups from that table. A decode from last year is as good as one from today for make, model and body.
• Re-decode only rows with error 8 or many empty fields, every few months: manufacturers keep filing data, and a VIN that decoded to the make alone may decode fully later.
• Keep the raw row next to your mapped fields, so a better mapping later does not need a new request.

Coverage gaps: where vPIC has little to say

vPIC describes vehicles made or imported for sale in the United States. Outside that, expect gaps:

• Cars built for other markets. A European-market Renault or a Korean domestic-market car usually decodes to the make and the model year at best, often with error 7 or 8. The manufacturer never filed its descriptor scheme with NHTSA.
• Older vehicles. Detail thins out the further back you go, and VINs from before the 1981 model year are not standardised at all.
• Trucks, trailers and incomplete vehicles. Multi-stage vehicles decode the chassis, not the body built on it.
• Grey imports. A car imported privately into the US decodes as whatever the original market filed, which may be nothing.

For a European or Asian car, the reliable sources of model detail are the manufacturer's own records or the listing the car came from. vPIC is still worth a call: the make and model year it returns can confirm that the VIN is plausible. Our guide on how to decode a VIN covers what you can read from the characters without any API.

How we use vPIC for Copart and IAAI records

Copart and IAAI lots do not always carry every specification. A listing may lack the body type, the drive, the fuel or the cylinder count, depending on how the lot was entered. In the AuctionsAPI Copart and IAAI feed we fill eight such specifications from vPIC by VIN, only when they are missing at the source: body type, vehicle type, make, model, model year, drive wheels, fuel type and cylinder count.

Two rules keep this honest. A value is added only when vPIC returns one: an empty DriveType stays empty, and a cylinder count is taken only when it is a positive number. And nothing is guessed from similar cars or other model years. If vPIC has no data, the field stays null in the vehicle object, and your code should treat null as unknown, the same way you treat an empty vPIC value.

Where vPIC fits in a VIN pipeline

Validate the VIN locally first (length, allowed characters, check digit for North American cars), decode it once with vPIC, store the raw row, and map only the fields you trust. vPIC tells you what the car is; it says nothing about what happened to it. For that you need history: auction lots by VIN through /search-vin (our guide to auction history by VIN shows what to look for), or title and accident data from a report provider.