VIN Horsepower API - Vehicle API Blog

You need reliable horsepower from a VIN for pricing, eligibility, or underwriting, and you want to ship it with minimal moving parts. By the end of this guide, you will decode a VIN and read engine.hp from Vehicle API, understand the response envelope and null behaviors, and productionize with caching, quotas, and error handling—all focused on the VIN horsepower field.

What the VIN horsepower field represents

The VIN Horsepower API is simply the engine.hp field returned by Vehicle API’s VIN decoder. It is a numeric horsepower rating as published by the NHTSA vPIC program for the decoded vehicle configuration.

Field: data.engine.hp
Type: integer
Units: horsepower (hp)
Source: NHTSA vPIC (United States). If the source does not publish horsepower for a VIN, the field will be null.

VIN decoding works worldwide for 17-character VINs, but the fullest metadata coverage is for US-market vehicles. Powertrain fields not published by NHTSA (or not applicable to the VIN) return as null. This is not a vehicle history report; it does not include title, accident, or ownership history.

Endpoint and authentication

Endpoint: POST https://vehicles-api.com/api/v1/vin/decode

Base URL: https://vehicles-api.com/api/v1
Auth: X-API-Key: YOUR_API_KEY header (Authorization: Bearer YOUR_API_KEY also works)
Body: JSON with a 17-character VIN
Response envelope: status, source, data on success; or status=error with error.code and error.message on failure

Response source indicates the upstream dataset used to produce the decode. For VIN horsepower, it is nhtsa. Dutch plates from RDW are supported in other lookups and never include a VIN; horsepower for those is outside the scope of this article. Recalls, complaints, and NCAP ratings are US-market only and matched by make, model, and year (and are not part of this horsepower decode).

See the full API reference in the Documentation.

Quickstart: curl request to read VIN horsepower

Use the official docs example below to test your connection. The control VIN decodes to a 2003 Honda Accord with 240 hp.

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

If the request succeeds, data.engine.hp will be 240 for this control VIN. In your application, replace the VIN with your user’s VINs. Cache decodes to minimize round trips and stay within your monthly quota.

Parse engine.hp in code

The following Python sample calls the same endpoint and extracts data.engine.hp. It also shows how to handle nulls and the response envelope.

import json
import requests

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

def get_vin_horsepower(vin: str) -> int | None:
headers = {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
}
payload = {"vin": vin}
resp = requests.post(API_URL, headers=headers, data=json.dumps(payload), timeout=10)

# Basic envelope and HTTP checks
resp.raise_for_status()
body = resp.json()

# Expect an envelope with status and data on success
if body.get("status") != "success":
# Error envelope example: {"status":"error","error":{"code":"...","message":"..."}}
err = body.get("error", {})
raise RuntimeError(f"Vehicle API error: {err.get('code')} - {err.get('message')}")

data = body.get("data", {}) or {}
engine = data.get("engine", {}) or {}
hp = engine.get("hp")

# hp can be None if not published by the source
return hp

if __name__ == "__main__":
vin = "1HGCM82633A004352"
hp = get_vin_horsepower(vin)
if hp is None:
print("Horsepower not available for this VIN.")
else:
print(f"VIN {vin} horsepower: {hp} hp")

Official example response

This is the exact JSON from the documentation for the control VIN. Use it to prototype your parser and unit tests.

{
"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 actually use for horsepower workflows

status: "success" indicates a successful decode. Always check this before reading data.
source: "nhtsa" tells you the upstream dataset for this decode.
data.vin: Echo of the submitted VIN to correlate responses with requests.
data.valid: Boolean validation result for the VIN format and checksum.
data.year, data.make, data.model, data.trim: Basic fitment context you may display with horsepower.
data.engine.hp: The horsepower value (integer). For the control VIN, 240.
data.engine.displacement_l, data.engine.cylinders, data.engine.configuration, data.engine.model: Additional engine attributes useful for UI or rules.
data.fuel_type and data.engine.fuel: Expected fuel; EV-related fields are null in this gasoline example.
data.transmission.style and data.transmission.speeds: Can be displayed alongside horsepower.
Null behaviors: electrification_level, ev_drive_unit, battery_kwh, charger_level, charger_power_kw, and drive are null here; design for nulls.

Coverage, scope, and null fields

VIN decoding works worldwide for 17-character VINs. The horsepower field is most complete for US-market vehicles because the upstream source in this endpoint is the NHTSA vPIC dataset. If a specific horsepower is not published for a given VIN, engine.hp will be null.

US-market safety datasets (recalls, owner complaints, NCAP crash ratings) are matched by make + model + year and are US-only. They are not returned by this horsepower decode call.
Dutch plates from RDW open data are supported via plate lookups elsewhere in the API and never include a VIN; horsepower in those contexts may differ and is out of scope for this VIN endpoint.
Do not expect title, accident, or ownership history; Vehicle API is not a vehicle history report.

Plan for nulls by making engine.hp optional in your schema. In UI, omit the row or display “N/A” rather than zero unless your business logic explicitly requires a fallback.

Caching and performance

VIN decodes are deterministic. Cache the entire response keyed by VIN for at least several days to reduce latency and conserve your monthly quota. When you deploy across services, a shared cache (for example, Redis) prevents duplicate decodes under bursty load.

Cache key: vin:{VIN}
Invalidate: rarely required; vPIC data is stable for historical VINs.
Retry: only on transient network errors or 5xx; use exponential backoff. Do not retry 4xx.

If you need a local agent interface for tools or AI runtimes, the same decode is available via the MCP server at https://vehicles-api.com/mcp.

Quotas and rate limits

All plans include a 7-day free trial, with the Starter plan beginning at $19/month. Rate limits and monthly quotas apply. Handle HTTP 429 by backing off and using your cache before retrying. For current limits and plan details, see the Documentation and your account dashboard at vehicles-api.com.

Error handling and troubleshooting

Every response uses a standard envelope. On success: status is "success" with source and data. On error: status is "error" with an error object providing code and message.

VIN length/format: Ensure exactly 17 characters; reject or sanitize at the edge.
Invalid VIN checksum: You may still receive a decode attempt depending on source; always check data.valid. If false, decide whether to display hp or prompt for correction.
Missing horsepower: If engine.hp is null, display “N/A” or route to manual verification.
Auth errors: Verify X-API-Key header; do not include other auth schemes in the same request.
429 Too Many Requests: Serve from cache and retry after a short delay; coordinate concurrency to respect rate limits.

Log the entire envelope (excluding API keys) for observability. Include vin, status, source, and, when present, error.code and error.message.

Designing your horsepower feature

Recommended request flow

Validate VIN locally for length and allowed characters.
Check cache; if hit, return cached horsepower immediately.
On miss, POST to /vin/decode with X-API-Key and JSON body.
Verify status == "success" and data.valid == true.
Read data.engine.hp. If null, handle gracefully.
Cache the full response for future requests.

Data model tips

engine.hp: integer nullable
engine.displacement_l: float nullable (liters)
engine.cylinders: integer nullable
transmission.style, transmission.speeds: display-only fields; keep nullable

Testing and monitoring

Unit tests: Use the official JSON above to assert your parser reads engine.hp = 240.
Contract tests: Check the envelope keys (status, source, data) exist on every success.
Null tests: Simulate null engine.hp to verify UI and downstream logic.
Performance: Measure P95 end-to-end with cache enabled; log cache hit ratio.

Security and operations

Store YOUR_API_KEY in a secure secret store or environment variable; never hardcode in client apps.
Send requests over HTTPS only.
Rate limiting: apply client-side throttling per VIN to prevent redundant bursts.
Idempotency: The decode is read-only; repeat requests for the same VIN return the same data.

FAQ

Does the horsepower field cover non-US vehicles?
VIN decoding works worldwide for 17-character VINs, but horsepower is fullest for US-market vehicles. If horsepower is not published for a given VIN, engine.hp will be null.

Is this a vehicle history report?
No. This endpoint provides decoded specs including horsepower. It does not include title, accident, or ownership history.

What if data.valid is false?
Treat the VIN as invalid for your workflow. You may still receive partial data, but it’s safer to prompt the user to correct the VIN before using horsepower downstream.

How should I handle monthly quota and rate limits?
Cache decoded VINs and back off on HTTP 429 responses. For your current limits, check the dashboard and the API docs.

Can I access the same decode via an AI or tool agent?
Yes. Vehicle API also runs as an MCP server at MCP, which you can integrate with your agent runtime.

Start decoding VIN horsepower in minutes. Every plan includes a 7-day free trial and the Starter is $19/month. Create your key now: Register. For full endpoint details, see the Documentation at vehicles-api.com.

Topics

VIN horsepower API API development guide decode VIN for horsepower vehicle API response engine horsepower data