You need reliable engine specifications from a VIN so your app can quote insurance, normalize listings, or verify fitment. By the end of this guide, you will decode a VIN into structured engine data (cylinders, displacement, configuration, model code, horsepower, and fuel) using Vehicle API’s VIN Engine Specs endpoint, understand the response envelope, and handle errors, caching, and nulls in production.
What you get from the VIN Engine Specs endpoint
The VIN Engine Specs capability is part of VIN decoding at Vehicle API. You submit a 17-character VIN and receive a normalized JSON payload with engine details under the data.engine object, plus related vehicle metadata (year, make, model, trim, transmission, plant, etc.). VIN decoding works worldwide, with the most complete results for US-market vehicles. Fields not published by NHTSA come back as null. This is not a vehicle history report—no title, accident, or ownership history is included.
Coverage notes you should plan for in code:
- VIN decoding: worldwide; most complete for US-market vehicles.
- US safety data (recalls, owner complaints, NCAP crash ratings): US-market only, matched by make + model + year. Not part of this endpoint’s engine object but useful context if you join datasets later.
- Dutch plate data: from RDW open data and never includes a VIN. Keep plate flows separate from VIN flows.
Prerequisites: account, API key, and base URL
All requests use the base URL https://vehicles-api.com/api/v1. Authenticate with your API key in the X-API-Key header. Authorization: Bearer is also accepted if your tooling prefers that header, but we’ll use X-API-Key throughout.
- Create your account and start the 7-day free trial (Starter is $19/mo after trial): Register
- Copy YOUR_API_KEY from the dashboard.
- Keep the base URL and endpoint handy: POST https://vehicles-api.com/api/v1/vin/decode.
If you are building an AI agent or system that speaks the Model Context Protocol (MCP), you can also connect to the Vehicle API MCP server at MCP. For REST integrations, continue below.
Step 1: Send the official curl request
Use the control VIN 1HGCM82633A004352 for testing. It decodes to a 2003 Honda Accord. The engine is gasoline; do not expect EV fields here—they intentionally come back as null in the official example.
cURL (copy/paste)
curl -X POST "https://vehicles-api.com/api/v1/vin/decode" -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"vin":"1HGCM82633A004352"}'Step 2: Read the official JSON response
Every response is an envelope containing status, source, and data on success. On errors, status is error and you receive error.code and error.message. Here is the official example for the control VIN (fields exactly as published in the docs):
{
"status": "success",
"source": "nhtsa",
"data": {
"vin": "1HGCM82633A004352",
"valid": true,
"year": 2003,
"make": "HONDA",
"model": "Accord",
"trim": "EX-V6",
"body": "Coupe",
"doors": 2,
"vehicle_type": "PASSENGER CAR",
"engine": {
"cylinders": 6,
"displacement_l": 3,
"configuration": "V-Shaped",
"model": "J30A4",
"hp": 240,
"fuel": "Gasoline"
},
"fuel_type": "Gasoline",
"electrification_level": null,
"ev_drive_unit": null,
"battery_kwh": null,
"charger_level": null,
"charger_power_kw": null,
"drive": null,
"transmission": {
"style": "Automatic",
"speeds": 5
},
"plant": {
"country": "UNITED STATES (USA)",
"city": "MARYSVILLE",
"state": "OHIO"
},
"manufacturer": "AMERICAN HONDA MOTOR CO., INC."
}
}Fields you will typically use for engine specs:
- data.engine.cylinders (integer)
- data.engine.displacement_l (liters, integer or float)
- data.engine.configuration (e.g., Inline, V-Shaped)
- data.engine.model (manufacturer engine code, e.g., J30A4)
- data.engine.hp (horsepower, as reported by NHTSA)
- data.engine.fuel and data.fuel_type (normalized fuel descriptors)
Additional supporting fields that help you match or display the engine correctly in your system:
- data.year, data.make, data.model, data.trim
- data.transmission.style and data.transmission.speeds
- data.plant.country, data.plant.city, data.plant.state
- data.valid for basic VIN validity
Nulls to expect and handle defensively:
- Electrification fields (electrification_level, ev_drive_unit, battery_kwh, charger_level, charger_power_kw) are null when not applicable or unpublished by NHTSA.
- drive can be null if not published (e.g., some records omit AWD/FWD/RWD).
Step 3: Call the endpoint from code
Below are production-ready client snippets you can adapt. They post the VIN to the same endpoint, include the X-API-Key header, and extract engine fields from the response envelope.
Python (requests)
import json
import requests
BASE_URL = "https://vehicles-api.com/api/v1"
API_KEY = "YOUR_API_KEY"
def decode_vin_engine(vin: str):
url = f"{BASE_URL}/vin/decode"
headers = {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
}
payload = {"vin": vin}
resp = requests.post(url, headers=headers, data=json.dumps(payload), timeout=15)
resp.raise_for_status() # Network/HTTP errors
body = resp.json()
# Envelope handling
if body.get("status") != "success":
err = body.get("error", {})
code = err.get("code", "unknown_error")
msg = err.get("message", "Unknown error")
raise RuntimeError(f"Vehicle API error: {code} - {msg}")
data = body.get("data", {}) or {}
engine = data.get("engine", {}) or {}
# Extract fields you actually need
return {
"vin": data.get("vin"),
"year": data.get("year"),
"make": data.get("make"),
"model": data.get("model"),
"trim": data.get("trim"),
"engine_cylinders": engine.get("cylinders"),
"engine_displacement_l": engine.get("displacement_l"),
"engine_configuration": engine.get("configuration"),
"engine_model_code": engine.get("model"),
"engine_hp": engine.get("hp"),
"engine_fuel": engine.get("fuel"),
"fuel_type": data.get("fuel_type"),
"transmission_style": (data.get("transmission") or {}).get("style"),
"transmission_speeds": (data.get("transmission") or {}).get("speeds"),
}
if __name__ == "__main__":
result = decode_vin_engine("1HGCM82633A004352")
print(json.dumps(result, indent=2))Handling the response envelope, errors, and nulls
All successful responses look like the example above: status is success, source indicates the upstream dataset (nhtsa for VIN decode), and data contains the decoded attributes. If a field is not published by NHTSA for that VIN, it returns as null rather than being omitted—this lets you distinguish “known empty” from “key missing.” In strongly typed code, treat these as optional values.
Error responses set status to error and include error.code and error.message. Common causes include:
- Authentication: missing or invalid X-API-Key header.
- Validation: vin is missing, not 17 characters, or malformed.
- Rate limiting or quota exceeded: you will receive a 4xx or 5xx with an error envelope—respect backoff and consult your plan’s limits.
Do not assume engine fields are always populated, even for valid VINs. NHTSA coverage varies by make, model, year, and market. Always check for nulls and keep downstream formatting robust (e.g., do not concatenate nulls into strings).
Caching decoded VINs for performance and cost
VINs are immutable identifiers, and decoded results for a given VIN are stable within the bounds of the source catalog. To reduce latency and stay inside rate limits and quota, cache successful decodes keyed by VIN.
- Cache key: vin string (e.g., “1HGCM82633A004352”).
- Suggested TTL: pick a duration that fits your update cadence. While VIN specs rarely change, upstream datasets can receive occasional corrections. If you need the freshest possible data, store an ETag-like fingerprint in your cache alongside a last-checked timestamp and periodically refresh in the background.
- Handle nulls consistently: cache the full response even when some fields are null so you do not hammer the endpoint trying to “fill in” non-existent fields.
Production details that save time
- Authentication: set the X-API-Key header with YOUR_API_KEY for every request. Authorization: Bearer also works if needed by your HTTP client.
- Content type: send JSON with Content-Type: application/json.
- Timeouts and retries: use a sane request timeout (e.g., 10–20 seconds) and backoff on transient network errors. Do not retry on validation errors.
- Units: displacement_l is liters, hp is horsepower as published by NHTSA. Doors is an integer count. Transmission.speeds is an integer.
- Normalization: make, model, and trim are capitalized according to NHTSA’s data; apply your own case normalization if your UI requires it.
- Idempotency: the endpoint is read-only; repeat calls with the same VIN return the same decode subject to source corrections.
- Envelope invariants: Do not parse fields outside data on success. Always check body.status first.
- Logging: log status, error.code, and error.message on failures. Avoid logging full VINs if your privacy policy restricts that; consider hashing the VIN.
Rate limits, monthly quota, and monitoring
Vehicle API applies plan-based rate limits and monthly quotas. Exact numbers vary by plan and are subject to change; review the Documentation and your dashboard for current limits. Implement client-side throttling and cache results to minimize duplicate requests. Monitor for HTTP 429 or error envelopes signaling quota/rate limit events and back off accordingly.
Common integration patterns for engine specs
- Dealer and marketplace listings: decode the VIN provided by sellers and map engine model (e.g., J30A4), cylinders, displacement, and horsepower to your catalog facets. Use transmission fields to further disambiguate trims where needed.
- Insurance quoting: extract engine displacement and horsepower to drive risk pricing rules while caching decodes per VIN to keep latencies low.
- Fleet operations: pre-decode every VIN in your fleet and store core engine attributes so maintenance systems can order correct parts. Use plant data to flag region-specific variations.
- AI agents and MCP: if your agent framework supports MCP, connect to the Vehicle API MCP server at MCP and call the same capability without building HTTP glue.
Testing with the control VIN before going live
Use the provided control VIN 1HGCM82633A004352 to verify your integration logic for success envelopes, null handling, and field extraction. Confirm you correctly parse:
- data.engine.cylinders = 6
- data.engine.displacement_l = 3
- data.engine.configuration = “V-Shaped”
- data.engine.model = “J30A4”
- data.engine.hp = 240
- data.engine.fuel and data.fuel_type = “Gasoline”
- Electrification fields are null and safely ignored in UIs.
Next, test a small representative sample of real VINs from your production data. Expect some fields to be null, especially for non-US markets or edge trims. Ensure your UI degrades gracefully (e.g., display “—” when horsepower is unavailable).
Troubleshooting tips
- HTTP 4xx with error envelope: check the request body schema, the VIN length (must be 17 characters), and the X-API-Key header.
- HTTP 429 or quota-related errors: implement retry with exponential backoff, add VIN result caching, and consider batching decodes during off-peak times.
- Unexpected nulls: remember that not all fields are published by NHTSA for every VIN. Validate assumptions in your business rules.
- Schema drift: stick to the documented keys. If you store results, map only the fields you need (engine and a few support fields) to avoid tight coupling.
Security and compliance notes
- Transport: use HTTPS only (the base URL is HTTPS).
- Secrets: do not hardcode YOUR_API_KEY in client-side code. Use server-side calls or a secure proxy for browser apps.
- PII: VINs uniquely identify vehicles; handle according to your privacy policy. Avoid logging full VINs where not necessary.
- Data lineage: the source field indicates the upstream dataset (nhtsa for decode). Keep it if you need audit trails.
Field-by-field recap for engine specs
Focus on these keys to implement “Engine Specs from VIN” end to end:
- data.vin: Echo of the input VIN; cache key.
- data.valid: Quick check that the VIN structure is valid.
- data.year, data.make, data.model, data.trim: Context for display and matching.
- data.engine.cylinders: Integer; display and filtering.
- data.engine.displacement_l: Liters; numeric comparisons and filtering.
- data.engine.configuration: String descriptor (e.g., V-Shaped); detail display.
- data.engine.model: Manufacturer engine code (e.g., J30A4); critical for fitment and parts catalogs.
- data.engine.hp: Horsepower figure; quoting and performance comparisons.
- data.engine.fuel and data.fuel_type: Normalized fuel descriptors.
- data.transmission.style and data.transmission.speeds: Helpful to disambiguate trims or build spec sheets.
Where this API fits with other datasets
The VIN Engine Specs endpoint stands on its own for spec normalization. For US-market vehicles, you can also join by year + make + model to US safety datasets (recall campaigns, owner complaints, NCAP crash ratings). Those datasets are US-only and are not part of this specific engine object. For Dutch plates, use RDW plate data separately; Dutch plates do not include a VIN, so do not expect to bridge directly from an RDW plate to a VIN using this endpoint.
Frequently asked questions
Does the VIN Engine Specs endpoint work outside the US?
Yes. VIN decoding works worldwide, with the most complete results for US-market vehicles. Fields not published for a given VIN return as null.
Which fields should I cache?
Cache the entire success envelope (status, source, data). At minimum, cache data.engine, data.year/make/model/trim, and data.vin as your key. Respect occasional upstream corrections by applying a reasonable TTL and background refresh.
How are errors returned?
Errors use the same envelope: status is error and the payload includes error.code and error.message. Check status first before reading data.
What about EVs and hybrids?
If the upstream source publishes electrification details, you will see them populated. Otherwise those fields (electrification_level, battery_kwh, charger_level, etc.) are null. Do not assume EV fields are present for gasoline vehicles.
Are recalls, complaints, and NCAP ratings included here?
No. Those are US-market safety datasets matched by make + model + year. The VIN Engine Specs endpoint provides decoding and engine specs; use separate endpoints or datasets for safety information.
Ready to ship VIN-to-engine specs in your app? Start your 7-day free trial and get your API key here: Register. For endpoint details, field definitions, and plan limits, see the Documentation. If you are integrating with AI agents, connect via MCP.