# Vehicle Data API — VIN decoder, recalls, NCAP safety ratings, complaints & EPA fuel economy (NHTSA + EPA, browserless, US-gov public-domain)

> decode a VIN → make/model/year/trim/engine/specs (vPIC)
> ReefAPI engine `vehicle` · 18 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/vehicle/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /vehicle/v1/vin_decode — 1 credit
decode a VIN → make/model/year/trim/engine/specs (vPIC)

**Parameters:**
- `vin` (string, required) — A Vehicle Identification Number, 1-17 chars (A-Z 0-9, no I/O/Q; use * for unknown positions in a partial VIN).
- `modelyear` (integer, optional) — Optional model year to disambiguate a partial VIN decode.
- `raw` (boolean, optional, default false) — If true, also include the full flat NHTSA attribute row(s) (~130 fields) under `attributes`.

**Returns:** vin, vehicle{} (make, model, modelYear, trim, engine, transmission, drivetrain, weight, plant, …), decode{} (errorCode/Text, suggestedVin)

**Example request body:**
```json
{
  "vin": "1HGCM82633A004352"
}
```

### POST /vehicle/v1/vin_decode_batch — 2 credits
decode up to 50 VINs in one call (vPIC batch)

**Parameters:**
- `vins` (array, required) — Up to 50 VINs. Either a 'VIN,year;VIN,year' string, or an array of VIN strings / [VIN, year] pairs / {vin, modelyear} objects.
- `raw` (boolean, optional, default false) — If true, also include the full flat NHTSA attribute row(s) (~130 fields) under `attributes`.

**Returns:** count, vehicles[] (each {vin, vehicle{}, decode{}})

**Example request body:**
```json
{
  "vins": "1HGCM82633A004352,2003;5UXWX7C5*BA,2011"
}
```

### POST /vehicle/v1/vin_decode_flat — 1 credit
per-variable VIN decode — one row per NHTSA variable with its label (the long-form companion to vin_decode)

**Parameters:**
- `vin` (string, required) — A Vehicle Identification Number, 1-17 chars (A-Z 0-9, no I/O/Q; use * for unknown positions in a partial VIN).
- `modelyear` (integer, optional) — Optional model year to disambiguate a partial VIN decode.

**Returns:** vin, count, variables[] (variable, value, variableId, valueId)

**Example request body:**
```json
{
  "vin": "1HGCM82633A004352"
}
```

### POST /vehicle/v1/fuel_economy — 1 credit
EPA fuel economy — MPG/MPGe (city/highway/combined), CO2, annual fuel cost, EV range. By year+make+model (auto-resolves trims) or EPA id

**Parameters:**
- `id` (integer, optional) — An EPA fuel-economy vehicle id (from fuel_economy_options). Provide this OR year+make+model.
- `year` (integer, optional) — Model year (e.g. 2021). EPA covers 1984–present.
- `make` (string, optional) — Vehicle make / brand (e.g. Honda, BMW, Acura). Case-insensitive; matched against NHTSA's catalog.
- `model` (string, optional) — Vehicle model name (e.g. Accord, RDX). Case-insensitive.

**Returns:** by id → vehicle{} (mpg{city,highway,combined}, fuelType, co2GramsPerMile, annualFuelCostUsd, fuelEconomyScore, ev{range}); by year+make+model → vehicles[]{} per trim

**Example request body:**
```json
{
  "year": "2021",
  "make": "Toyota",
  "model": "Camry"
}
```

### POST /vehicle/v1/fuel_economy_options — 1 credit
list EPA trims (each → an id for fuel_economy) for a year+make+model

**Parameters:**
- `year` (integer, required) — Model year (1984–present).
- `make` (string, required) — Vehicle make / brand (e.g. Honda, BMW, Acura). Case-insensitive; matched against NHTSA's catalog.
- `model` (string, required) — Vehicle model name (e.g. Accord, RDX). Case-insensitive.

**Returns:** year, make, model, count, options[] (id, trim, epaModel)

**Example request body:**
```json
{
  "year": "2021",
  "make": "Toyota",
  "model": "RAV4"
}
```

### POST /vehicle/v1/fuel_prices — 1 credit
current US national average fuel prices (regular/midgrade/premium/diesel/e85/electric/cng/lpg)

**Parameters:** none

**Returns:** prices{} (per fuel type, USD/gal or USD/kWh)

### POST /vehicle/v1/canadian_specs — 1 credit
dimensional & weight specs (length, width, height, wheelbase, curb weight, track) from NHTSA's Canadian vehicle database

**Parameters:**
- `year` (integer, required) — Model year (1984–present).
- `make` (string, optional) — Vehicle make (exact spelling, case-insensitive; matched against NHTSA's Canadian database).
- `model` (string, optional) — Optional model filter (substring, matched server-side).

**Returns:** year, make, model, count, specs[] (OL/OW/OH length-width-height, WB wheelbase, CW curb weight, TWF/TWR track widths)

**Example request body:**
```json
{
  "year": "2011",
  "make": "Acura"
}
```

### POST /vehicle/v1/recalls — 1 credit
safety recalls by make+model+modelYear, or by campaignNumber

**Parameters:**
- `make` (string, optional) — Vehicle make / brand (e.g. Honda, BMW, Acura). Case-insensitive; matched against NHTSA's catalog.
- `model` (string, optional) — Vehicle model name (e.g. Accord, RDX). Case-insensitive.
- `modelYear` (integer, optional) — 4-digit model year (e.g. 2012).
- `campaignNumber` (string, optional) — An NHTSA recall campaign number — looks up that single campaign directly (alternative to make+model+modelYear).

**Returns:** count, recalls[] (campaignNumber, component, summary, consequence, remedy, parkIt/parkOutSide, units affected)

**Example request body:**
```json
{
  "make": "acura",
  "model": "rdx",
  "modelYear": "2012"
}
```

### POST /vehicle/v1/safety_ratings — 1 credit
NCAP star ratings + crash-test media; by vehicleId, or year+make+model (auto-resolves variants), or drill-down

**Parameters:**
- `vehicleId` (integer, optional) — NHTSA NCAP VehicleId for a direct safety rating (from a prior year+make+model drill-down).
- `modelYear` (integer, optional) — 4-digit model year (e.g. 2012).
- `make` (string, optional) — Vehicle make / brand (e.g. Honda, BMW, Acura). Case-insensitive; matched against NHTSA's catalog.
- `model` (string, optional) — Vehicle model name (e.g. Accord, RDX). Case-insensitive.

**Returns:** by vehicleId → rating{}; by year+make+model → vehicles[]{rating}; partial → drill-down list (modelYears / makes / models)

**Example request body:**
```json
{
  "vehicleId": "7523"
}
```

### POST /vehicle/v1/complaints — 1 credit
consumer complaints by make+model+modelYear

**Parameters:**
- `make` (string, required) — Vehicle make / brand (e.g. Honda, BMW, Acura). Case-insensitive; matched against NHTSA's catalog.
- `model` (string, required) — Vehicle model name (e.g. Accord, RDX). Case-insensitive.
- `modelYear` (integer, required) — 4-digit model year (e.g. 2012).

**Returns:** count, complaints[] (odiNumber, components, summary, crash/fire, injuries/deaths, dates)

**Example request body:**
```json
{
  "make": "acura",
  "model": "rdx",
  "modelYear": "2012"
}
```

### POST /vehicle/v1/models — 1 credit
models for a make (optionally a modelYear / vehicleType)

**Parameters:**
- `make` (string, required) — Vehicle make / brand (e.g. Honda, BMW, Acura). Case-insensitive; matched against NHTSA's catalog.
- `modelYear` (integer, optional) — 4-digit model year (e.g. 2012).
- `vehicleType` (string, optional) — Vehicle type filter (e.g. car, truck, mpv, motorcycle, bus, trailer). Case-insensitive; matched against NHTSA's catalog.

**Returns:** make, count, models[] (modelId, model, makeId)

**Example request body:**
```json
{
  "make": "honda"
}
```

### POST /vehicle/v1/makes — 0 credits
all makes, or makes for a vehicleType (car/truck/mpv/motorcycle/...)

**Parameters:**
- `vehicleType` (string, optional) — Vehicle type filter (e.g. car, truck, mpv, motorcycle, bus, trailer). Case-insensitive; matched against NHTSA's catalog.

**Returns:** count, makes[] (makeId, make, vehicleType when filtered)

**Example request body:**
```json
{
  "vehicleType": "car"
}
```

### POST /vehicle/v1/manufacturers — 1 credit
all manufacturers (paged) or details for one

**Parameters:**
- `manufacturer` (string, optional) — Manufacturer name or id to fetch details for; omit to page the full list.
- `page` (integer, optional, default 1) — Page number for the full manufacturer list (~100 per page).

**Returns:** count, manufacturers[] (mfrId, mfrName, mfrCommonName, country, vehicleTypes)

### POST /vehicle/v1/wmi_decode — 1 credit
decode a 3-char WMI to its manufacturer

**Parameters:**
- `wmi` (string, required) — A 3-character World Manufacturer Identifier (the first 3 VIN chars).

**Returns:** wmi + decoded fields (Make, Manufacturer, country, …)

**Example request body:**
```json
{
  "wmi": "1HG"
}
```

### POST /vehicle/v1/manufacturer_wmis — 1 credit
all WMIs registered to a manufacturer

**Parameters:**
- `manufacturer` (string, required) — Manufacturer name or id (a `make` is also accepted) whose registered WMIs to list.

**Returns:** manufacturer, count, wmis[] (wmi, name, country, vehicleType, dateAvailableToPublic)

### POST /vehicle/v1/vehicle_types — 0 credits
vehicle types produced by a make

**Parameters:**
- `make` (string, required) — Vehicle make / brand (e.g. Honda, BMW, Acura). Case-insensitive; matched against NHTSA's catalog.

**Returns:** make, count, vehicleTypes[] (vehicleTypeId, vehicleType)

**Example request body:**
```json
{
  "make": "honda"
}
```

### POST /vehicle/v1/product_options — 0 credits
recall/complaint enumeration tree (modelYears → makes → models; issueType=r|c)

**Parameters:**
- `issueType` (enum, optional, default "r") — Which enumeration tree to walk: r = recalls, c = complaints. Any value other than c/complaint(s) is treated as r. [one of: r, c]
- `modelYear` (integer, optional) — Optional model year: with no make → makes for that year; with a make → models. Omit both → the list of available model years.
- `make` (string, optional) — Optional make to drill product_options down to its models.

**Returns:** issueType, level (modelYears/makes/models), and the matching list under that key

**Example request body:**
```json
{
  "issueType": "r",
  "modelYear": "2012"
}
```

### POST /vehicle/v1/plant_codes — 1 credit
equipment (tire) plant codes for a year

**Parameters:**
- `year` (integer, required) — Production year for the equipment (tire) plant codes.
- `equipmentType` (enum, optional, default "1") — NHTSA equipment type code for plant codes (default 1 = tires). [one of: 1, 3, 13]
- `reportType` (enum, optional, default "New") — Which plant-code report slice to return (default New). [one of: New, Updated, All]

**Returns:** year, equipmentType, reportType, count, plants[]

**Example request body:**
```json
{
  "year": "2021"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=vehicle
- Human docs page: https://reefapi.com/docs/vehicle
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt