How to Use the VIN Horsepower API

By Vehicle API
How to Use the VIN Horsepower API

You need horsepower by VIN without chasing spec sheets or scraping half-structured pages. By the end of this guide, you’ll decode a VIN, read engine.hp from the response, and ship a robust integration using Vehicle API’s VIN horsepower endpoint.

What you get from the VIN horsepower endpoint

The VIN horsepower API is simply the VIN decoder at Vehicle API with a focus on engine.hp. You send a 17-character VIN and receive a normalized JSON envelope with status, source, and data. Inside data, the engine object includes hp (horsepower), plus supporting details like cylinders, displacement_l, configuration, model, and fuel.

Illustration: How to Use the VIN Horsepower API

Coverage notes you should plan for:

  • VIN decoding works worldwide for any 17-character VIN, with the fullest coverage for US-market vehicles.
  • Fields NHTSA does not publish return as null. Do not assume a missing value means zero; treat null as “unknown.”
  • US safety data (recalls, complaints, NCAP ratings) are US-market only and matched by make + model + year. This guide stays on horsepower from the VIN decoder, not safety datasets.
  • Dutch plate lookups are from RDW open data and never include a VIN. This post focuses on decoding a VIN directly.
  • This is not a vehicle history report (no title, accident, or ownership history).

Start your 7-day trial and get your API key

You can be in production quickly with the 7-day free trial available on every plan (Starter is $19/mo after trial). To begin:

  1. Create your account: Register.
  2. Open your dashboard and copy your API key.
  3. Use the X-API-Key header to authenticate. Authorization: Bearer YOUR_API_KEY also works if that fits your stack, but we’ll use X-API-Key in samples.

The base URL for REST is https://vehicles-api.com/api/v1. There’s also an MCP server if your agent or service uses MCP: MCP.

Make your first horsepower lookup with cURL

Copy this cURL request, replace YOUR_API_KEY with the key from your dashboard, and run it in your terminal. The control VIN decodes to a 2003 Honda Accord and is provided for testing. It’s not your user’s car.

cURL

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

Understand the JSON response

Every response is wrapped in an envelope with status, source, and data on success. When there’s an issue, you get status: "error" with error.code and error.message. Below is the official example response for the control VIN. You will use data.engine.hp to pull horsepower and related engine metadata as needed.

Official JSON

{
    "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 for horsepower-driven features

  • status: "success" or "error". Check this before reading data.
  • source: "nhtsa" indicates NHTSA vPIC was used for decoding.
  • data.vin: Echo of the queried VIN, useful for logging and correlation ids.
  • data.valid: Boolean VIN validity flag at decode time.
  • data.year, data.make, data.model, data.trim: Normalize your inventory attributes.
  • data.engine.hp: The horsepower value you’ll surface in your UI or calculations.
  • data.engine.cylinders, data.engine.displacement_l, data.engine.configuration, data.engine.model: Optional context for spec sheets and search facets.
  • data.fuel_type and data.engine.fuel: Fuel metadata; electrification fields are null in this gasoline example and will be null if not published by NHTSA.
  • data.transmission.style and data.transmission.speeds: Good for merchandising or underwriting rules that consider transmission.
  • data.plant and data.manufacturer: Provenance details; helpful for quality checks or regulatory displays.

Read horsepower in your code

Below is a minimal Python example that decodes a VIN and extracts engine.hp alongside a few descriptive fields. It uses the same endpoint and adheres to the response envelope.

Python

import json
import requests

API_KEY = "YOUR_API_KEY"
URL = "https://vehicles-api.com/api/v1/vin/decode"
VIN = "1HGCM82633A004352" # Control VIN for testing

headers = {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
}

payload = {"vin": VIN}

resp = requests.post(URL, headers=headers, json=payload, timeout=15)
resp.raise_for_status() # HTTP-level errors

data = resp.json()

if data.get("status") != "success":
err = data.get("error", {})
code = err.get("code")
message = err.get("message")
raise RuntimeError(f"Vehicle API error: {code} - {message}")

source = data.get("source")
vehicle = data.get("data", {})

vin = vehicle.get("vin")
year = vehicle.get("year")
make = vehicle.get("make")
model = vehicle.get("model")
trim = vehicle.get("trim")

engine = vehicle.get("engine") or {}
horsepower = engine.get("hp") # int or None
cylinders = engine.get("cylinders")
displacement_l = engine.get("displacement_l")

print(f"Decoded from {source}: {vin} - {year} {make} {model} {trim}")
print(f"Horsepower (engine.hp): {horsepower}")
print(f"Engine: {cylinders} cyl, {displacement_l}L")

Notes:

  • Authenticate with the X-API-Key header. Authorization: Bearer YOUR_API_KEY is also accepted if that fits your client standard.
  • Always check status before reading data.* keys. Errors return status: "error" with error.code and error.message (see below).
  • Use .get and null-safe accessors to handle null fields gracefully (e.g., unknown drive type or electrification values).

Practical details that save you time

Response envelope and errors

Every response is an envelope. On success you’ll see:

  • status: "success"
  • source: e.g., "nhtsa"
  • data: the decoded VIN object (see official JSON above)

On error you’ll see:

  • status: "error"
  • error.code: a short machine-readable string
  • error.message: a human-readable explanation to log or display

Handle both the HTTP status code and the JSON envelope. For example, surface error.message to your logs and map error.code to your retry/backoff policy if appropriate.

Rate limits and monthly quota

Every plan has rate limits and a monthly quota. If you exceed these, you’ll receive an error with status: "error" and an explanatory message. Monitor your usage in the dashboard and implement backoff when you see throttling at peak times. If your workload bursts (bulk VIN normalizations, nightly syncs), schedule them to respect plan limits and cache results to avoid re-decoding the same VIN repeatedly.

Caching decoded VINs

  • VIN decoding is effectively static for a given VIN. Cache by VIN key to avoid redundant calls.
  • Store at least the fields you display or compute with, including engine.hp, year, make, model, trim, and engine.* you surface.
  • Because some fields can be null if not published by the source, your cache schema should allow nulls without coercion to zero or empty strings.

Units and formatting

  • engine.hp is horsepower as an integer.
  • engine.displacement_l is liters.
  • doors is a count of doors as an integer.

Null fields and guarded parsing

  • Expect null for fields not published by NHTSA (e.g., drive may be null, EV fields are null for gasoline vehicles).
  • Do not convert null to zero or “Unknown 0.” Show “Unknown” or omit the row in your UI.
  • Keep your serializer tolerant of absent nested objects (e.g., engine or transmission) by using null-safe accessors.

Build a reliable horsepower lookup workflow

Step 1: Validate and normalize input

  • Ensure VINs are uppercased and exactly 17 characters before calling the API.
  • Store the raw VIN and the normalized VIN in your logs for traceability.

Step 2: Decode once, cache forever (or until policy refresh)

  • Call POST /vin/decode with the VIN and cache the response envelope or at least data.* fields you need.
  • Set a refresh policy that suits your business (for example, refresh on-demand if you encounter nulls you want to check again later). Avoid periodic re-decodes unless there’s a reason.

Step 3: Map engine.hp into your domain model

  • Store horsepower in your vehicle table as engine_hp or similar, plus year, make, model, and trim for faceting and display.
  • When a value is null, preserve null as-is and let your UI compute a user-friendly fallback label.

Step 4: Handle errors and quotas

  • On non-2xx HTTP status codes, retry with exponential backoff only when it makes sense (avoid tight loops).
  • On status: "error" responses, log error.code and error.message. Some errors should not be retried (e.g., invalid VIN).
  • Alert if you approach your monthly quota to avoid mid-month surprises.

Working with MCP for AI agents

If you build AI agents or tools that use Model Context Protocol (MCP), you can access the same VIN horsepower data via the Vehicle API MCP server. This is useful when your LLM tooling can call MCP tools directly instead of making raw HTTP requests. Learn more and configure your client here: MCP.

Production checklist for VIN horsepower

  • Authentication: Use X-API-Key with YOUR_API_KEY in server-side code or secure environments.
  • Endpoint: POST https://vehicles-api.com/api/v1/vin/decode
  • Payload: {"vin":"…"}; only 17-character VINs are valid.
  • Envelope: Check status first; then read data.*.
  • Horsepower: data.engine.hp (integer). Guard for null.
  • Nulls: Treat as unknown; do not coerce.
  • Caching: Cache by VIN. Avoid duplicate decodes.
  • Logging: Store vin, status, and source for traceability.
  • Quotas: Monitor usage; implement backoff on throttling.
  • Docs: Keep the schema at hand: Documentation.

Troubleshooting common issues

  • VIN fails validation (status: "error"): Confirm it’s exactly 17 characters and uppercase. Some fonts confuse 0 and O.
  • engine.hp is null: Some trims or markets may not publish horsepower via NHTSA. Keep null, avoid zero, and consider displaying a neutral “Unknown horsepower.”
  • Drive or electrification fields are null on gasoline vehicles: That’s expected when not published by the source.
  • Repeated timeouts: Add a reasonable client timeout and retry with jitter. Also cache successful decodes to reduce load.
  • Mismatch with marketing brochures: VIN decoders normalize specs by VIN; brochures may list range-wide marketing claims. Use the decoder’s VIN-specific fields for inventory integrity.

Reference: Endpoint and envelope

  • Endpoint: POST https://vehicles-api.com/api/v1/vin/decode
  • Headers: X-API-Key: YOUR_API_KEY; Content-Type: application/json
  • Body: {"vin":"1HGCM82633A004352"}
  • Success: {"status":"success","source":"nhtsa","data":{...}}
  • Error: {"status":"error","error":{"code":"...","message":"..."}}

FAQ

Does VIN decoding cover vehicles outside the US?
Yes. VIN decoding works worldwide for any 17-character VIN, with the fullest coverage for US-market vehicles. Some fields may be null if not published by the source.

Is horsepower always available?
No. engine.hp may be null for some vehicles or trims where horsepower is not published by NHTSA. Handle nulls gracefully and avoid substituting estimates.

How should I cache horsepower results?
Cache by VIN. VIN decode data is effectively static, so you can store the response (or the fields you need) and avoid re-decoding unless you have a policy reason to refresh.

Will I get recall or crash-test data in this response?
This endpoint focuses on VIN decoding. US safety data (recalls, complaints, NCAP ratings) are US-market only and matched by make + model + year, and are separate from the horsepower lookup shown here.

Can I use MCP instead of HTTP?
Yes. If your application or agent uses MCP, you can connect to the Vehicle API MCP server here: MCP.

Ready to add horsepower-by-VIN to your app? Start your 7-day free trial, get your key, and ship your integration today: Register. For full schema details and more examples, see the Documentation.

Topics

VIN horsepower API API development guide decode VIN vehicle API integration horsepower by VIN