You need to grab transmission details from a VIN reliably, normalize them, and ship them into dealer tools, quotes, listings, or an agent’s prompt. By the end of this guide you’ll decode any 17‑character VIN with Vehicle API and read the transmission field (style, speeds) in a consistent shape you can cache and display.
What the transmission field returns and why it matters
The VIN decode endpoint includes a transmission object with two keys you will actually use in production:
- transmission.style — human-readable style (for example, Automatic, Manual, CVT) when published by NHTSA vPIC; null if not provided.
- transmission.speeds — integer count of forward speeds/gears when available; null if not provided.
Vehicle API decodes VINs worldwide. Coverage is fullest for US-market vehicles because it standardizes on NHTSA’s vPIC data. If a transmission detail is not published by NHTSA for a given VIN, you’ll see null. Treat this as “unknown,” not an error.
Endpoint and authentication
Base URL: https://vehicles-api.com/api/v1
Endpoint: POST /vin/decode
Authentication: send your key in the X-API-Key header (Authorization: Bearer YOUR_API_KEY also works). Content-Type must be application/json. The request body includes a single field, vin, with a 17‑character VIN.
Every response is a simple envelope:
- status — "success" for decodes that resolved; "error" for failures.
- source — "nhtsa" for VIN decodes.
- data — the decoded object on success, including transmission.style and transmission.speeds.
On error, the envelope includes error.code and error.message. Use error.code for programmatic branching and error.message for logs and user-facing hints.
For reference material and field definitions, see the Documentation. If you want to integrate the same decode capability into an AI agent via a tool-calling server, see MCP.
cURL you can copy
This is the official request you can paste into your terminal. It posts a single VIN and returns a structured decode including transmission:
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 example with transmission
Below is the official response for the control VIN, a 2003 Honda Accord. Copy this to design your parsing logic. Note the transmission object.
{
"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’ll actually use
- data.transmission.style — string. Example: "Automatic". Display as-is. Consider a fallback label like "Unknown transmission" if null.
- data.transmission.speeds — integer. Example: 5. Use for filtering, comparisons, or badges like "5-speed". If null, omit the badge.
- data.vin and data.valid — use to key your cache and confirm checksum validity.
- data.year, data.make, data.model, data.trim — helpful for context when you render transmission alongside other specs. Do not rely on these to infer transmission if the transmission object is null.
Note on EV/hybrids: electrification fields are present in the same envelope but depend on source publication. For the control VIN they are null. Do not infer transmission type from EV nulls; handle each field independently.
JavaScript example: decode a VIN and normalize transmission
This sample posts to the same endpoint, extracts transmission details, applies safe fallbacks, and demonstrates simple in-memory caching keyed by VIN.
async function decodeVinTransmission(vin, apiKey) {
const cache = decodeVinTransmission.cache || (decodeVinTransmission.cache = new Map());
if (cache.has(vin)) return cache.get(vin);
const res = await fetch("https://vehicles-api.com/api/v1/vin/decode", {
method: "POST",
headers: {
"X-API-Key": apiKey,
"Content-Type": "application/json",
},
body: JSON.stringify({ vin })
});
const payload = await res.json();
if (payload.status !== "success") {
const code = payload?.error?.code || "decode_error";
const message = payload?.error?.message || "VIN decode failed";
throw new Error(`${code}: ${message}`);
}
const tx = payload.data?.transmission || {};
// Normalize output
const result = {
vin: payload.data?.vin || vin,
valid: Boolean(payload.data?.valid),
year: payload.data?.year || null,
make: payload.data?.make || null,
model: payload.data?.model || null,
transmission_style: tx.style || null, // "Automatic" or null
transmission_speeds: Number.isInteger(tx.speeds) ? tx.speeds : null // 5 or null
};
cache.set(vin, result);
return result;
}
// Usage
decodeVinTransmission("1HGCM82633A004352", "YOUR_API_KEY")
.then(data => {
// Render e.g., "Automatic (5-speed)" with safe fallbacks
const style = data.transmission_style || "Unknown transmission";
const speeds = data.transmission_speeds != null ? ` (${data.transmission_speeds}-speed)` : "";
console.log(`${style}${speeds}`);
})
.catch(err => console.error(err.message));Nulls, coverage, and safe fallbacks
VIN decoding works for any 17‑character VIN worldwide. NHTSA vPIC publication is strongest for US-market vehicles, so international VINs may return null in transmission.style or transmission.speeds even when the vehicle obviously has a transmission. Handle these cases gracefully:
- Display a neutral label like “Unknown transmission” when style is null.
- Omit gear-count badges if speeds is null.
- Never guess transmission from engine displacement, body, or trim.
The API also exposes safety data (recalls, complaints, NCAP crash ratings) for US-market vehicles only, matched by make + model + year. That data is outside the scope of the transmission field and does not change transmission parsing.
Dutch plates are sourced from RDW open data and never include a VIN. Because the transmission field comes from VIN decoding, do not expect transmission from a Dutch plate lookup alone.
Response envelope, errors, and retries
All responses return an envelope with status and source. Production code should always branch on status before touching data:
- status: "success" — data is present; transmission may still be null if not published.
- status: "error" — read error.code and error.message for the failure condition.
Common failure categories you should anticipate:
- Invalid VIN format (not 17 characters) — do client-side validation before posting.
- Auth errors — missing or invalid X-API-Key.
- Rate limiting — handle 429s with exponential backoff and cache successful decodes aggressively.
- Upstream data not available — rare, but treat as retriable and return a graceful user message.
Do not treat null transmission fields as errors; this reflects source publication limits rather than a request failure.
Performance, rate limits, and monthly quota
Vehicle API enforces rate limits and monthly quotas by plan. Exact thresholds vary by subscription and are shown in your account dashboard. To preserve quota and improve UX:
- Cache decodes by VIN. A VIN’s decode is stable; store it server-side with a long TTL and revalidate on a schedule that fits your workflow.
- Debounce user input. Only call the endpoint when the input is a valid 17‑character VIN.
- Use the response envelope to short-circuit rendering for failures; don’t retry immediately on client unless you’ve inspected error.code.
Starter is $19/mo and every plan includes a 7‑day free trial you can start immediately. You can register and get an API key directly on Register.
Normalization tips for transmission.style and transmission.speeds
NHTSA vPIC normalizes most style names, but you should still design for consistent rendering and filters:
- Case handling — style arrives in title case; render directly or map to your preferred casing.
- Synonyms — you can map “Automatic” and “Auto” together in your UI, but do not alter the source field in your stored record; keep a UI-only mapping layer.
- Partial data — when speeds is present but style is null, render “5‑speed” without the style label.
- Filtering — base filters on normalized values stored alongside the raw fields to avoid re-mapping on every query.
MCP server for agent tool-calling
If you’re building an agent that needs to fetch transmission from a VIN during a conversation, you can call the same decode capability through the MCP server: MCP. It exposes the decode operation as a tool your agent can invoke with a VIN string. The same response envelope and transmission fields apply; null handling and caching logic should mirror your API integration.
Testing checklist before shipping
- Input validation: reject non‑17‑character strings client-side before calling the API.
- Happy path: verify transmission.style and transmission.speeds render as “Automatic (5‑speed)” for the control VIN.
- Null path: simulate a response where transmission is { style: null, speeds: null } and confirm your UI labels degrade gracefully.
- Error path: mock a 401 and ensure you surface a clear message to internal users while withholding technical details from end users.
- Caching: confirm you do not re-hit the API for the same VIN within your TTL and that cache invalidation works as designed.
- Rate limiting: backoff behavior kicks in on 429 without cascading failures across your requests.
Security and privacy notes
- Keys: send X-API-Key over HTTPS only. Do not embed keys in client-side apps; proxy through your backend.
- PII: VIN decodes do not include owner data or vehicle history. This is not a vehicle history report; it returns specs and safety datasets only.
- Logging: log the VIN, status, error.code, and timing; avoid logging full payloads in production unless required for debugging.
Operational guidance
- Idempotency: repeated POSTs with the same VIN return the same decode. Treat the endpoint as functionally idempotent for a given VIN version.
- Resilience: wrap network calls with timeouts and retries that respect rate limits; prefer cached data when the network is down.
- Versioning: reference the Documentation for any schema updates. Null fields may appear when source data has gaps; this is expected.
FAQ
Does the transmission field cover non‑US VINs?
Yes. VIN decoding works worldwide, but coverage is fullest for US‑market vehicles. For some international VINs, transmission.style or transmission.speeds may be null if not published by the source.
Can I infer transmission when the field is null?
No. Do not infer transmission from engine or trim. Render a neutral label or omit the field when null.
How should I cache transmission results?
Key your cache by VIN. Cache the full decode payload, including transmission, with a long TTL. Revalidate on a schedule appropriate for your app. The same VIN’s specs rarely change once published.
Are recalls or crash ratings tied to the transmission?
No. Recalls, complaints, and NCAP ratings are US‑market only and matched by make + model + year. They do not affect the transmission field.
Can I get transmission from a Dutch plate (RDW)?
Dutch plates from RDW do not include a VIN. The transmission field is available via VIN decoding; do not expect it from a Dutch plate alone.
Ready to add reliable VIN transmission decoding to your app? Start your 7‑day free trial and get an API key in minutes on Register. For more endpoints and field references, explore the Documentation, and if you’re building an agent, wire in the MCP server to let tools call the same decode.
