VIN Engine Specs API

Your app needs trustworthy engine specifications from a VIN: cylinders, displacement, configuration, horsepower, and fuel type. By the end of this guide you’ll be able to decode a VIN with Vehicle API, extract the engine specs you need from a consistent JSON envelope, handle nulls and errors, and ship a cached, production-grade integration.

What you get from the VIN engine specs field

The VIN decoding endpoint provides an engine object with the most useful powertrain attributes for downstream workflows like lead qualification, appraisal, underwriting, and parts fitment. You’ll receive cylinders, displacement in liters, engine configuration, internal engine model code, rated horsepower, and fuel. The same decode response also includes adjacent fields you may need, such as vehicle year/make/model/trim, transmission, and fuel type at the top level.

Data is sourced from NHTSA vPIC and normalized in a single envelope. Coverage is worldwide for VIN decoding, with the fullest attribute completeness for US-market vehicles. Fields NHTSA does not publish are returned as null. This is not a vehicle history report: it does not include title, accident, or ownership history.

Endpoint and authentication

Vehicle API exposes VIN decoding as a single JSON REST endpoint and as an MCP server. This article focuses on the REST endpoint and the engine specs field:

• Endpoint: POST https://vehicles-api.com/api/v1/vin/decode
• Auth: send X-API-Key: YOUR_API_KEY (an Authorization: Bearer YOUR_API_KEY header also works)
• Body: a JSON object with the 17-character VIN

Every response is returned in an envelope with:

• status string: success or error
• source string when successful (e.g., nhtsa)
• data object when successful, or error.code and error.message when not

You can browse the full API reference and endpoint details in the Documentation and explore the MCP server for agents at MCP. New users can start building with a 7‑day free trial.

Try it with curl

Use the control VIN to see a complete engine object. Replace YOUR_API_KEY with your key.

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"}'

Official JSON response

This is the official example response from the documentation. It decodes the control VIN and includes the engine specs. Note that electrification fields are null because this VIN is a gasoline vehicle; do not expect EV fields to be populated on ICE vehicles.

{
"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."
}
}

Python example: decode a VIN and read engine specs

This Python snippet calls the same endpoint, checks the response envelope, handles potential nulls, and extracts the engine properties you’ll typically persist.

import json
import sys
import requests

API_URL = "https://vehicles-api.com/api/v1/vin/decode"
API_KEY = "YOUR_API_KEY"
VIN = "1HGCM82633A004352"

def decode_vin(vin: str) -> dict:
headers = {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
}
resp = requests.post(API_URL, headers=headers, json={"vin": vin}, timeout=10)
# Raise on transport-level errors; the API still returns an envelope in the body
resp.raise_for_status()
payload = resp.json()

if payload.get("status") != "success":
# Standardized error envelope
code = payload.get("error", {}).get("code")
msg = payload.get("error", {}).get("message")
raise RuntimeError(f"VIN decode failed: {code} - {msg}")

return payload

try:
result = decode_vin(VIN)
src = result.get("source")
data = result.get("data", {})
engine = data.get("engine") or {}

engine_specs = {
"vin": data.get("vin"),
"year": data.get("year"),
"make": data.get("make"),
"model": data.get("model"),
"trim": data.get("trim"),
"fuel_type": data.get("fuel_type"),
"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"),
"source": src,
}

# Null-safe printing; you can persist this dict as-is
print(json.dumps(engine_specs, indent=2))
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
sys.exit(1)

In production, persist the full data object so you can support downstream features (e.g., transmission-aware filters). For engine-focused use cases, the subset above usually suffices.

The engine fields you’ll use

The engine object is your primary source for powertrain data. In the official example, these are the most actionable fields:

• engine.cylinders (integer): Number of cylinders. Useful for performance scoring and insurance rating.
• engine.displacement_l (number): Displacement in liters. Store and display in L; convert to cc if needed downstream.
• engine.configuration (string): Engine layout (e.g., V-Shaped, Inline). Handy for parts lookup and enthusiast marketplaces.
• engine.model (string): Internal engine code (e.g., J30A4). Critical for exact-fit parts and repair databases.
• engine.hp (integer): Horsepower. For appraisal, valuation heuristics, and trim disambiguation.
• engine.fuel (string): Fuel used by the engine. For fuel-type constraints and EV/ICE branching logic.

Closely related, top-level fuel_type often mirrors engine.fuel but is maintained alongside other vehicle attributes. When present on both, prefer engine.fuel for engine-centric logic and keep fuel_type for cross-cutting UI filters.

Some fields may be null depending on region and publication completeness. Always null-check before applying numeric operations.

Coverage and data sources

• VIN decoding: worldwide; attribute completeness is fullest for US-market vehicles.
• Engine specs come from NHTSA vPIC when available; non-published fields return null.
• US safety data (recalls, owner complaints, NCAP crash ratings) is US-market only and matched by decoded make + model + year. These safety datasets are separate from engine specs and may be integrated later in your workflow.
• Dutch plates are available via RDW open data and do not include a VIN. Plate-based lookups are out of scope here but can complement VIN flows where appropriate.

If you need an agent-ready interface to the same data, the MCP server is available at MCP, ideal for tools that broker VIN decoding or engine spec lookups via AI runtimes.

Response envelope, errors, and nulls

Always program against the envelope rather than raw fields:

• Check status. If it is success, read source and data.
• If status is error, read error.code and error.message for machine- and human-readable diagnostics.
• Expect null for fields NHTSA does not publish for that VIN or market.

Recommended patterns:

• Validate VIN length (17 chars) before requesting to catch basic input issues client-side.
• Guard reads with get(...) or optional chaining and default to null rather than fabricating values.
• Log the source to support auditability (e.g., nhtsa).

Performance: caching, rate limits, and quotas

VIN decoding is deterministic for a given 17-character VIN; the decoded attributes do not change frequently. To reduce latency and cost:

• Cache successful VIN decodes keyed by VIN. A long-lived cache is appropriate; invalidate or refresh selectively if you observe source updates.
• Deduplicate concurrent lookups by VIN to avoid thundering herds in busy workflows (e.g., bulk imports).

Vehicle API enforces plan-based monthly quotas and rate limits. Exact thresholds depend on your plan. Monitor usage in your dashboard and implement graceful handling for 429/limit conditions. For specifics, check the Documentation or contact support via the console.

Units and normalization details

• Displacement is returned in liters as displacement_l. If you need cubic centimeters, multiply by 1000 and round per your display rules.
• Horsepower is the rated figure supplied by the source; it is not dynamically dyno-corrected. Do not infer torque unless it is present (it is not in the example and may be null or absent).
• Fuel naming is standardized at the API layer when possible; still plan for common variants (e.g., “Gasoline” vs “Petrol”) across markets and versions.

Error handling strategies that save time

• Transport vs. logical errors: The server can return an HTTP error (transport) or a JSON envelope with status: "error" (logical). Handle both: raise on non-2xx HTTP, then inspect the envelope.
• Idempotency: VIN decode is a pure function; safe to retry reads on transient failures with exponential backoff.
• Input sanitation: Trim whitespace and uppercase VINs before requests. Reject strings with forbidden characters or incorrect length locally.

Production checklist for VIN engine specs

• Implement POST /api/v1/vin/decode with X-API-Key header and JSON body containing vin.
• Parse the envelope; bail on status: "error" and surface error.code and error.message to logs or UI.
• Map and persist the engine fields you need: cylinders, displacement_l, configuration, model, hp, fuel. Also store fuel_type and identifiers like vin, year, make, model, trim.
• Null-safety: Treat missing engine fields as null. Do not inject defaults that could mislead pricing or fitment logic.
• Caching: Cache by VIN after a successful decode. Prefer read-through cache to minimize latency for hot VINs.
• Observability: Log source, request IDs (if present in headers), and outcome for debugging.
• Quotas: Monitor usage to avoid rate limit exceedances; back off or queue non-urgent decodes.

Notes on adjacent datasets

While your focus here is engine specs from VIN decode, many applications enrich the same decoded vehicle (year/make/model) with US-market safety datasets:

• Recall campaigns
• Owner complaints
• NCAP crash ratings

These are matched by year + make + model for US-market vehicles only and can be integrated after you store the base decode. Keep in mind that Dutch plate data from RDW never includes a VIN; treat plate-based enrichment as a separate path in your pipeline. Do not promote US plate lookup; it is not live.

MCP access for agents and tools

If you’re building AI agents or tooling that speak MCP, Vehicle API is also available at MCP. The MCP server exposes the same VIN decoding capability so your agent can fetch engine specs without custom HTTP scaffolding. Keep the same post-processing rules as above: check the envelope, extract engine, and null-check fields.

FAQ

Does VIN decoding work outside the US?
Yes. VIN decoding works worldwide. Attribute completeness is fullest for US-market vehicles. Fields not published by NHTSA (or available for a given market) may be null.

Are recalls, complaints, and NCAP ratings included with engine specs?
They are separate US-market datasets matched by year + make + model. The VIN engine specs come from the decode response; safety datasets can be added later in your flow.

Why are some engine fields null?
If the source does not publish a field for that VIN, the API returns null. Do not substitute defaults; handle nulls explicitly in your UI and logic.

Can I use Bearer auth instead of X-API-Key?
Yes. Both X-API-Key: YOUR_API_KEY and Authorization: Bearer YOUR_API_KEY work. Use one consistently.

How should I cache decodes?
Cache by VIN after a successful decode. VIN-derived specs are stable; a long-lived cache reduces latency and conserves your monthly quota. Refresh on demand if you detect updates.

Start integrating engine specs from VIN today. Create your account for the 7‑day free trial and get an API key here: Register. For endpoint details, review the Documentation on vehicles-api.com and deploy to your stack.