You need to tell whether a vehicle runs on gasoline, diesel, flex fuel, or something else—reliably, from a VIN. By the end of this guide, you’ll be able to fetch and parse the VIN fuel_type from Vehicle API, verify it against engine.fuel, and handle nulls, rate limits, and errors in production.
What you get from the VIN Fuel Type lookup
The Vehicle API exposes fuel type via VIN decoding. You call a single endpoint and receive a normalized JSON envelope with status, source, and data. Within data, you’ll use two keys for fuel: fuel_type and engine.fuel. These are sourced from NHTSA vPIC for VIN decoding and work worldwide (coverage is fullest for US-market vehicles; fields that NHTSA does not publish come back null).
This is not a vehicle history report: there is no title, accident, or ownership history. US safety datasets (recalls, owner complaints, NCAP crash ratings) are available in the broader API and are matched by make + model + year for US-market vehicles only. Dutch plates from RDW do not include a VIN and are outside the scope of this VIN endpoint.
Get access: free trial, key, and endpoints
Start with a 7-day free trial and the Starter plan at $19/month. Create your account, copy your key, and you’re ready to call the API.
- Sign up: Register
- Read the API reference: Documentation
- Build an AI integration with the MCP server: MCP
Base URL: https://vehicles-api.com/api/v1
Authentication is via the X-API-Key header (Authorization: Bearer also works). Keep your key in server-side code or secure secrets storage.
Endpoint for VIN fuel type
Use the VIN Decode endpoint. It returns a single JSON envelope containing core vehicle specs and fuel attributes. For this guide, we’ll use the official control VIN (1HGCM82633A004352). This control VIN is a 2003 Honda Accord gasoline coupe; the electrification fields are null by design, and you must not invent EV values.
Endpoint: POST https://vehicles-api.com/api/v1/vin/decode
cURL (official sample)
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"}'JSON (official sample)
{
"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 use
- status: "success" or "error". Always check before reading data.
- source: "nhtsa" for VIN decoding. Helpful for audit trails and debugging.
- data.vin: Echo of the decoded VIN. Verify it matches your request.
- data.valid: Boolean, if the VIN checksum/structure is valid.
- data.fuel_type: Normalized top-level fuel (e.g., "Gasoline"). Use this for UI and rules engines.
- data.engine.fuel: Engine-sourced fuel (“Gasoline” in this example). Use as a cross-check and for engine-specific logic.
- data.electrification_level, data.battery_kwh, data.charger_level, data.charger_power_kw: Null for non-EVs/hybrids; do not infer values.
- Other useful context: year, make, model, trim, engine specs, transmission, and plant—handy for display and matching safety datasets by year/make/model.
End-to-end: from key to fuel type in code
Below is a minimal JavaScript example that sends the same request as the cURL sample and reads the fuel fields for downstream logic. Keep the VIN as-is for testing, then swap in user VINs in production.
JavaScript (Node.js fetch) example
import fetch from "node-fetch";
async function getVinFuelType(vin) {
const res = await fetch("https://vehicles-api.com/api/v1/vin/decode", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({ vin })
});
// Network- and HTTP-level handling
if (!res.ok) {
throw new Error(`HTTP ${res.status}`);
}
const payload = await res.json();
// Envelope handling
if (payload.status !== "success" || !payload.data) {
const code = payload?.error?.code ?? "unknown_error";
const msg = payload?.error?.message ?? "Unexpected API response";
throw new Error(`${code}: ${msg}`);
}
const data = payload.data;
// Preferred field for UI / policy engines
const fuelType = data.fuel_type; // e.g., "Gasoline"
// Cross-check with engine.fuel where available
const engineFuel = data.engine?.fuel ?? null; // e.g., "Gasoline"
// Null-safe electrification hints (expect null for the control VIN)
const electrification = {
level: data.electrification_level,
batteryKwh: data.battery_kwh,
chargerLevel: data.charger_level,
chargerPowerKw: data.charger_power_kw
};
return {
vin: data.vin,
valid: data.valid,
fuelType,
engineFuel,
electrification
};
}
// Example usage with the official control VIN:
getVinFuelType("1HGCM82633A004352")
.then(info => {
console.log("VIN:", info.vin);
console.log("Fuel type:", info.fuelType);
console.log("Engine fuel:", info.engineFuel);
console.log("Electrification (should be nulls for this VIN):", info.electrification);
})
.catch(err => {
console.error("VIN decode failed:", err.message);
});How to interpret fuel_type vs engine.fuel
- Use data.fuel_type as the canonical fuel label for UI and business rules. It is normalized and consistent.
- Use data.engine.fuel for engine-oriented workflows. It often matches fuel_type; keep it as a secondary check.
- When either field is null, do not guess. VIN decoding depends on what NHTSA publishes for that VIN range. Missing fields return null.
- For EVs and hybrids, consult electrification fields (electrification_level, battery_kwh, etc.). If they are null, treat the vehicle as non-electrified unless fuel_type indicates otherwise.
Coverage and data sources you should plan around
- VIN decoding works worldwide. Coverage is fullest for US-market vehicles, as the source is NHTSA vPIC. Fields not published by NHTSA are null.
- US safety datasets (recalls, owner complaints, NCAP) exist elsewhere in Vehicle API and are matched by make + model + year for US-market vehicles only.
- Dutch license plates are sourced from RDW open data and never include a VIN; they’re separate from VIN decoding.
This context matters for your data model: keep fields nullable, and treat VIN-decoded fuel data as authoritative for US-market coverage while accommodating nulls globally.
Response envelope, errors, and retry strategy
Every response returns an envelope:
- Success: { "status": "success", "source": "nhtsa", "data": { ... } }
- Error: { "status": "error", "error": { "code": "...", "message": "..." } }
Check status first. On "error", inspect error.code and error.message. Common HTTP statuses you should handle include 400 (bad request, e.g., malformed body), 401 (invalid or missing API key), 404 (resource not found), 429 (rate limited), and 5xx (transient server or upstream issues).
- 400: Validate that vin is a 17-character string before sending.
- 401: Ensure X-API-Key is present and correct; rotate keys if compromised.
- 429: Implement exponential backoff and retry with jitter. Consider local caching to avoid repeat decodes.
- 5xx: Retry with backoff. If persistent, surface a clear message to operators.
Rate limits, monthly quota, and caching
Your rate limit and monthly quota are enforced by the platform and visible in your dashboard. Build with the following in mind:
- Cache decoded VINs. VINs are stable identifiers; decoded specs and fuel types don’t change for a given VIN. Cache them indefinitely in your database or CDN. This sharply reduces 429s and latency.
- Use background prefetching. If your workflow expects the same VINs (e.g., a dealer roster), pre-decode and cache them.
- Batch gracefully. If you need to process many VINs, respect rate limits and stagger requests.
- Null-tolerant schemas. Store nulls without coercion and surface them as “Unknown” or equivalent in UI.
Production notes for marketplaces, fleets, insurance, and agents
- Normalization: Use fuel_type for display and policy checks; log engine.fuel alongside it for traceability and audits.
- Compliance and auditing: Keep source so you can prove where each datum came from ("nhtsa" for VIN decoding).
- International VINs: Expect more nulls outside the US market. Don’t reject a VIN solely because non-critical fields are null.
- Agent and tool integrations: If you’re building AI agents that reason over vehicle data, consider the MCP server at MCP to expose VIN decoding as a tool with a consistent contract.
Testing checklist
- Decode the official control VIN 1HGCM82633A004352 and assert data.fuel_type === "Gasoline".
- Verify status === "success" and source === "nhtsa".
- Assert null on electrification fields for the control VIN.
- Exercise error handling by removing the X-API-Key header locally and expecting a non-2xx HTTP with an "error" envelope.
- Throttle test to confirm 429 handling and retry/backoff behavior.
Operational guardrails and observability
- Logging: Log status, error.code, error.message on failures. On success, log vin, source, and a hash of the payload (for privacy) to detect schema changes.
- Metrics: Track request rates, 2xx/4xx/5xx splits, and cache hit rate for VIN decodes. Aim for a high cache hit rate.
- Alerting: Alert on sustained spikes in 4xx/5xx or a sudden increase in nulls for critical fields like fuel_type.
- Schema stability: The envelope (status, source, data) is consistent. Still, write parsers that ignore unknown extra fields to remain forward-compatible.
Security and privacy
- Key management: Keep X-API-Key server-side. Rotate keys regularly.
- PII: VINs are not PII, but treat them as sensitive in logs if your policies require it.
- Client apps: Proxy requests through your backend to avoid exposing the key in client-side code.
When your product also needs safety data or Dutch plates
If you need recalls, owner complaints, or NCAP crash ratings, remember those are available for US-market vehicles only and are matched by make + model + year. Keep that matching logic separate from VIN decoding. If you work with Dutch plates, use the RDW-backed endpoints; note that Dutch plate data never includes a VIN.
Troubleshooting common fuel type issues
- Null fuel_type: Use engine.fuel if present. If both are null, keep the value unknown; do not infer from market or year.
- Mismatched fuel_type vs engine.fuel: Prefer fuel_type for canonical labeling. Log the discrepancy; it may reflect source data granularity.
- Unexpected EV fields: For non-electrified vehicles, EV fields are null. Treat non-null values as authoritative when present.
- International VINs: Expect more nulls. Cache results and avoid repeated calls for the same VIN.
Quick reference
- Base URL: https://vehicles-api.com/api/v1
- Endpoint: POST /vin/decode
- Auth: X-API-Key: YOUR_API_KEY (Authorization: Bearer also supported)
- Envelope: status, source, data (or status: "error" with error.code, error.message)
- Fuel fields: data.fuel_type, data.engine.fuel
- EV fields: data.electrification_level, data.battery_kwh, data.charger_level, data.charger_power_kw (null for non-EV control VIN)
You can register today for a 7-day free trial directly on vehicles-api.com, then follow the Documentation to move from sandbox to production quickly.
FAQ
Does VIN decoding cover every country?
Yes, VIN decoding works worldwide. Coverage is fullest for US-market vehicles. Fields that NHTSA does not publish for a VIN range will return null.
Are safety datasets (recalls, complaints, NCAP) part of this response?
No. The example above is strictly VIN decoding. US safety datasets are available elsewhere in Vehicle API and are matched by make, model, and year for US-market vehicles only.
What should I do when fuel_type is null?
Check engine.fuel. If both are null, preserve null in your database and UI. Do not infer from geography or model year.
Do Dutch plates include a VIN?
No. Dutch plates are from RDW open data and never include a VIN. Use VIN decoding and RDW plate data as separate inputs.
How should I cache results?
Cache decoded VINs indefinitely. VIN-level specs, including fuel_type, are stable. Caching reduces latency and avoids rate limit issues.
Ship your fuel-type integration in minutes: create your account and start the 7-day free trial at Register, then continue with the endpoint details in the Documentation. If you’re building AI agents, explore the MCP server as a drop-in tool.