Side Crash Rating API

You need to programmatically retrieve NHTSA side crash-test star ratings for a vehicle and expose them inside your app without sifting through multiple datasets. By the end of this guide, you’ll be able to call the Vehicle API Side Crash Rating endpoint, parse side.driver and side.passenger stars, handle nulls and US-only coverage, and build a cache keyed to make–model–year so your UI stays fast.

What this endpoint returns and when to use it

The Side Crash Rating data comes from NHTSA NCAP and is available for US-market vehicles only. Ratings are matched by make + model + year derived from the supplied VIN. If NHTSA did not publish a specific star rating (for example, an “overall” score for a given body style), those fields can be null. Non-US VINs will return coverage_us_only with a 422 error.

Use this endpoint when you need reliable, official US NCAP star ratings in your dealer, marketplace, fleet or insurance flow. It’s not a vehicle history report; there is no title, accident or ownership history. For VIN decoding (year, make, model, trim, engine, transmission, assembly plant) Vehicle API aggregates NHTSA vPIC and works worldwide (fullest for US-market vehicles). Dutch plates are supported via RDW open data but do not include a VIN.

Vehicle API is available as a standard REST API and as an MCP server for agent runtimes. Explore the product at vehicles-api.com and the MCP server at MCP.

Endpoint and authentication

Base URL: https://vehicles-api.com/api/v1

Endpoint: GET /vin/safety-ratings

Query parameters:

• vin: the 17-character VIN to match against make + model + year.

Authentication:

• Send your key in the X-API-Key header. Authorization: Bearer is also supported, but examples below use X-API-Key.

Working, copy-pasteable request

The following is the official sample request. It uses a known control VIN so you can see the complete response structure. Replace YOUR_API_KEY with your key.

curl "https://vehicles-api.com/api/v1/vin/safety-ratings?vin=1HGCM82633A004352" -H "X-API-Key: YOUR_API_KEY"

Official JSON response example

Below is the official docs example you should use to build your parser. Fields may be null when NHTSA did not publish a value. Ratings are integers (stars) where present.

{
"status": "success",
"source": "nhtsa",
"data": {
"vin": "1HGCM82633A004352",
"coverage": "us",
"match": "partial",
"vehicle_description": "2003 Honda Accord 2-DR.",
"overall": null,
"front": {
"overall": null,
"driver": 5,
"passenger": 5
},
"side": {
"overall": null,
"driver": 5,
"passenger": 5
},
"rollover": 4,
"nhtsa_vehicle_id": 4736
}
}

Fields you will actually use

All responses use a consistent envelope with status, source, and data. For Side Crash Rating UX, you will typically read:

• data.coverage: "us" confirms this is a US-market match.
• data.match: "partial" or "exact" match against make + model + year (value may vary). Ratings are matched by MMY, not by an individual, unit-level crash test.
• data.vehicle_description: string suitable for a compact label (e.g., “2003 Honda Accord 2-DR.”).
• data.side.driver: integer stars (0–5) or null.
• data.side.passenger: integer stars (0–5) or null.
• data.side.overall: integer stars or null; can be null when NHTSA did not publish an overall side rating.
• data.rollover: integer stars (or null if not published) representing rollover resistance.
• data.front.driver and data.front.passenger: frontal ratings; show alongside side ratings if your UI displays all NCAP dimensions.
• data.overall: aggregate overall star rating across dimensions; can be null if not published.
• data.nhtsa_vehicle_id: NHTSA’s reference ID for the MMY bucket that the ratings map to.

Nulls are expected. Do not coerce null to 0. In your UI, prefer “Not rated” or hide the aggregate tile when overall is null, while still showing per-position ratings that are present.

Mapping the Side Crash Rating structure

Production-ready usage: cURL and code

cURL for quick testing

JavaScript example (Node.js or browser fetch)

async function getSideCrashRatings(vin) {
const url = `https://vehicles-api.com/api/v1/vin/safety-ratings?vin=${encodeURIComponent(vin)}`;
const res = await fetch(url, {
headers: {
"X-API-Key": "YOUR_API_KEY"
}
});

// Handle non-2xx with structured error parsing
if (!res.ok) {
let body;
try { body = await res.json(); } catch (_) {}
const code = body && body.error && body.error.code ? body.error.code : `http_${res.status}`;
const message = body && body.error && body.error.message ? body.error.message : res.statusText;
throw new Error(`Vehicle API error: ${code} - ${message}`);
}

const json = await res.json();

// Envelope: { status, source, data }
if (json.status !== "success" || !json.data) {
throw new Error("Unexpected response envelope");
}

const d = json.data;

// Read the fields you care about
const result = {
coverage: d.coverage, // "us" or null
match: d.match, // e.g., "partial" or "exact"
description: d.vehicle_description, // e.g., "2003 Honda Accord 2-DR."
sideDriver: d.side && d.side.driver != null ? d.side.driver : null,
sidePassenger: d.side && d.side.passenger != null ? d.side.passenger : null,
sideOverall: d.side && d.side.overall != null ? d.side.overall : null,
rollover: d.rollover != null ? d.rollover : null,
overall: d.overall != null ? d.overall : null,
nhtsaVehicleId: d.nhtsa_vehicle_id
};

return result;
}

// Example usage with the control VIN:
getSideCrashRatings("1HGCM82633A004352")
.then(console.log)
.catch(console.error);

Coverage, matching and null handling

Scope and matching:

• US-market only for NCAP crash ratings. If you pass a valid non-US VIN, you will receive an error with code coverage_us_only and HTTP 422.
• Matching is by make + model + year. The response can report match as partial; this is expected because NCAP buckets ratings by MMY, not by an individual VIN’s exact trim or options.

Nulls are normal in NCAP data:

• overall can be null even when individual dimensions (front, side, rollover) are present.
• Within front and side, overall may be null while driver and passenger ratings are present.

UI guidance:

• Render null as “Not rated” or omit the tile. Do not default to 0 stars; that misrepresents the source data.
• If coverage is not "us", do not display US ratings. Surface a clear message like “Not available for this market.”

Response envelope, errors and retry strategy

Envelope:

• status: "success" on success; otherwise "error".
• source: "nhtsa" for NCAP safety ratings.
• data: object with the fields described above.

Errors:

• On error, you get an envelope with status: "error" and an error object containing error.code and error.message.
• coverage_us_only returns HTTP 422 when you pass a non-US VIN to this endpoint.
• You may also see standard HTTP errors such as 401 for invalid/missing key, 429 if you exceed your plan’s rate limit, or 5xx for transient upstream conditions. Always read error.code and error.message for actionable detail.

Retries:

• For 429, back off and retry with exponential delay or reduce burst concurrency.
• For 5xx, retry with jitter; do not infinitely retry.
• Do not retry 4xx validation errors (e.g., malformed VIN or coverage_us_only); fix the input or suppress the feature for that market.

Rate limits, monthly quota and caching

Rate limits and monthly quota depend on your plan. If you exceed limits, the API returns an error (commonly 429). Check your dashboard for current limits and usage. Every plan includes a 7-day free trial so you can load-test your integration before committing.

Caching recommendations:

• Ratings are matched by make + model + year. Cache each response by VIN and also memoize by MMY to reuse across identical vehicles. This avoids redundant calls when browsing inventory lists.
• Set a conservative TTL (e.g., days to weeks). Ratings change rarely, but you should allow periodic refresh to pick up late-published values.
• Different trims in the same MMY usually share the same NCAP ratings, but do not assume; always trust the latest response.

Integration notes for global apps

VIN decoding coverage is global (fullest for US-market vehicles), while NCAP safety ratings, recalls, complaints are US-market only. For non-US users:

• Guard your UI: call safety-ratings, and if you receive coverage_us_only, hide the ratings module and continue with decoded specs.
• For Dutch registrations (RDW), you can retrieve plate data, but RDW plates never include a VIN. If you need NCAP ratings for Dutch inventory, you must supply a US-market VIN that maps to the same MMY, which is typically not applicable. Keep the feature US-only.

Explore more about Vehicle API products at vehicles-api.com and the developer reference at Documentation.

MCP server option for agents

If you’re building autonomous agents that need authoritative vehicle data, you can connect to the Vehicle API MCP server. It exposes the same capabilities (VIN decoding, US safety data) to tools-based runtimes so your agent can fetch side crash ratings from NHTSA through a consistent interface. Learn more at MCP.

End-to-end implementation checklist

• Validate the VIN client-side for length (17) before submitting.
• Call GET /vin/safety-ratings with the X-API-Key header.
• Parse the response envelope: require status === "success" and source === "nhtsa".
• Read data.coverage; if not "us", stop and show “Not available in this market.”
• Render data.side.driver and data.side.passenger. If data.side.overall is not null, render an overall side tile; otherwise hide or label “Not rated”.
• Optionally render data.front.* and data.rollover to give users the full NCAP picture.
• Respect nulls; never coerce to 0.
• Cache by VIN and also by MMY to reuse results across similar inventory items.
• Implement backoff on 429 and jittered retries for transient 5xx responses.

Troubleshooting common scenarios

• Why is overall null? NHTSA may not publish an overall value for certain years/body styles. Use the per-dimension ratings that do exist.
• Why is match "partial"? Ratings are matched by make + model + year, not every trim. Partial match still carries the correct NCAP stars for the MMY bucket.
• I got 422 coverage_us_only. This indicates you queried safety ratings for a non-US VIN. Suppress the ratings UI for that vehicle.
• Stars differ from marketing brochures. Always trust the values returned by source: "nhtsa" and do not average or combine fields yourself.

Security, headers and environments

• Send your key in the X-API-Key header in both server and client contexts. If calling from a browser, proxy requests through your backend to avoid exposing credentials.
• Authorization: Bearer YOUR_API_KEY is also supported if you prefer Authorization headers in existing middleware.
• Use separate keys for staging vs production so you can monitor and rotate independently.

Data freshness and consistency

• NCAP data is sourced directly from NHTSA. As NHTSA updates ratings, responses can change. Build your UI to tolerate fields becoming available after a refresh.
• Avoid persisting user-entered “stars” or manually edited ratings. Always fetch or refresh from the API to keep consistency with the authoritative source.

Quick QA plan before you ship

• Happy path: control VIN returns US coverage with side.driver and side.passenger populated; UI shows stars and “Not rated” for null aggregates.
• US-only check: simulate a non-US VIN and confirm you handle the 422 coverage_us_only error and hide the module.
• Null handling: ensure you do not crash if side.overall or overall is null.
• Caching: hit the endpoint twice for the same VIN; confirm second load comes from your cache.
• Throttling: simulate bursts to confirm backoff on 429 without breaking the user flow.

API operations you don’t need for this feature

This guide focuses on Side Crash Rating only. While Vehicle API also supports VIN decoding worldwide, US recalls, owner complaints, and NCAP rollover/frontal ratings, you do not need additional endpoints to render side-impact stars. Keep the integration minimal and rely on the single /vin/safety-ratings call.

FAQ

Does this endpoint return ratings for non-US vehicles?
No. NCAP ratings in this endpoint are US-market only. A valid non-US VIN will return an error with code coverage_us_only (HTTP 422).

Why is data.match sometimes "partial"?
NCAP ratings are matched by make + model + year, not by exact trim. Partial still indicates a valid MMY match from NHTSA.

Can any of the fields be missing?
Yes. Fields such as overall or side.overall can be null when NHTSA did not publish them. Always handle nulls gracefully.

How should I cache results?
Cache by VIN, and also memoize by make + model + year to reuse ratings across similar vehicles. Refresh periodically; ratings rarely change but they can be updated.

What does the response envelope look like on error?
status is "error" and the payload includes error.code and error.message. For non-US VINs, error.code is coverage_us_only.

Ready to add Side Crash Ratings to your app? Start your 7-day free trial and get an API key: Register. For full details on parameters and envelopes, see the Documentation or explore the product at vehicles-api.com.