NCAP Crash Ratings API - Vehicle API Blog

You need trustworthy crash-test stars you can plug into listings, pricing screens, or underwriting decisions. By the end of this guide you’ll query the NCAP Crash Ratings endpoint, parse the response envelope, handle US-only coverage and null fields, and cache results efficiently for dealer tools, marketplaces, fleet, insurance apps, or AI agents.

What the NCAP Crash Ratings endpoint provides

The NCAP Crash Ratings endpoint returns NHTSA New Car Assessment Program stars for frontal, side, and rollover tests. Ratings are delivered by make + model + year matching for US-market vehicles. The overall star rating and test-level “overall” fields can be null when NHTSA did not publish them for that configuration.

Coverage: US-market vehicles only for NCAP ratings. A valid non-US VIN returns an error with code coverage_us_only for this endpoint.
Match basis: make + model + year, not trim-level specifics. The response includes a match indicator so you know how exact the match was.
Vehicle data scope: Vehicle API can decode VINs worldwide (fullest for US-market vehicles). Dutch plates are available from RDW open data, but NCAP ratings remain US-only and plates never include a VIN.
Not a vehicle history report: This endpoint does not include title, accident, or ownership history.

Explore more at vehicles-api.com or use the MCP server if you’re wiring the API into an agent runtime.

Authentication and base URL

Base URL: https://vehicles-api.com/api/v1. Authenticate with the header X-API-Key: YOUR_API_KEY. An Authorization: Bearer YOUR_API_KEY header also works. Every response is wrapped in a standard envelope with status, source, and data on success, or status: "error" with error.code and error.message on failure.

All plans include a 7-day free trial (Starter is $19/mo). Start here: Register. See endpoint details in the Documentation.

Endpoint and required parameter

Endpoint: GET /vin/safety-ratings

Required query parameter: vin

Example: GET https://vehicles-api.com/api/v1/vin/safety-ratings?vin=1HGCM82633A004352

Quickstart: call with cURL

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

Note: The control VIN 1HGCM82633A004352 decodes to a 2003 Honda Accord. Use it to validate your integration; it is not your user’s car.

Official JSON response format

{
"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’ll use:

status: success or error. Use this first to branch your logic.
source: Data origin; for NCAP this is nhtsa.
data.vin: Echo of the VIN you requested.
data.coverage: us for NCAP data. Use to gate UI for US-only ratings.
data.match: Matching quality indicator (partial when ratings are matched by make + model + year without trim certainty). Use to annotate or footnote in UI.
data.vehicle_description: Human-readable label for display.
data.overall: Overall NCAP star rating; can be null if not published. UI should tolerate nulls.
data.front.driver, data.front.passenger: Frontal test stars (0–5). data.front.overall can be null.
data.side.driver, data.side.passenger: Side-impact stars (0–5). data.side.overall can be null.
data.rollover: Rollover resistance stars (0–5).
data.nhtsa_vehicle_id: NHTSA internal id. Useful for correlating with other NHTSA datasets.

JavaScript example: fetch and normalize the stars

This snippet calls the endpoint, handles the response envelope, and extracts the stars you’ll present in your app. It also demonstrates safe handling of nulls.

async function fetchNcapRatings(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'
// Or: 'Authorization': 'Bearer YOUR_API_KEY'
}
});

const json = await res.json();

if (json.status !== 'success') {
const code = json.error?.code || 'unknown_error';
const msg = json.error?.message || 'Request failed';
throw new Error(`${code}: ${msg}`);
}

const d = json.data;
return {
vin: d.vin,
coverage: d.coverage,
match: d.match,
label: d.vehicle_description,
overall: d.overall, // may be null
front: {
overall: d.front?.overall ?? null,
driver: d.front?.driver ?? null,
passenger: d.front?.passenger ?? null
},
side: {
overall: d.side?.overall ?? null,
driver: d.side?.driver ?? null,
passenger: d.side?.passenger ?? null
},
rollover: d.rollover ?? null,
nhtsaId: d.nhtsa_vehicle_id
};
}

// Example usage with the control VIN:
fetchNcapRatings('1HGCM82633A004352')
.then(r => {
console.log('Vehicle:', r.label);
console.log('Match:', r.match, 'Coverage:', r.coverage);
console.log('Overall:', r.overall);
console.log('Front - Driver:', r.front.driver, 'Passenger:', r.front.passenger);
console.log('Side - Driver:', r.side.driver, 'Passenger:', r.side.passenger);
console.log('Rollover:', r.rollover);
})
.catch(err => console.error('NCAP error:', err.message));

Handling the response envelope, nulls, and errors

Every response is an envelope. Always check status first:

status: "success": Read fields under data. Some fields (e.g., overall, front.overall, side.overall) can be null when NHTSA did not publish a combined star.
status: "error": Inspect error.code and error.message. For this endpoint, a valid non-US VIN yields error.code = coverage_us_only with HTTP 422. Use that to suppress a ratings widget outside the US.

Do not coerce null to 0 in UI. Treat missing stars as “not rated” rather than “zero stars.”

Coverage and matching specifics you need to account for

US-only ratings: If your inventory is mixed-market, call the endpoint and check status and any error.code. For other regions, you can still decode VINs via the VIN decoding endpoint (worldwide, fullest for US-market), but NCAP ratings won’t be available.
Match semantics: Ratings are matched by make + model + year. The match field tells you how specific the match is. Use a badge like “Ratings for this model year” if match is partial.
Dutch plates: RDW plate lookups don’t return a VIN and will not include NCAP ratings. If you start from a Dutch plate, you can still show plate-based specs but omit US NCAP stars.

Caching strategy for performance and cost

Both the dealer UX and pricing depend on fast UI. Cache decoded VINs and NCAP ratings results to avoid redundant calls:

VIN decoding cache: Persist decoded year/make/model/trim keyed by VIN. Many features (including safety ratings match) start with reliable YMM.
NCAP ratings cache: Since matching is at the make+model+year level, cache ratings keyed by a normalized tuple like {year, make, model}. Different VINs of the same model year can reuse the cached stars.
Null-friendly cache: Cache successful responses with null fields as-is. Nulls reflect NHTSA publication gaps and should not trigger a retry storm.
Expiry: Refresh on a sensible schedule (e.g., weekly) since NHTSA occasionally adds or revises entries. Ratings for legacy model years are stable; use a longer TTL there.

Rate limits and monthly quota

Plans have rate limits and monthly quotas. Exact numbers vary by plan; check your dashboard and the Documentation. Practical guidance:

Coalesce duplicate requests per page load (e.g., listings page showing many VINs from the same model year).
Use the caching approach above to cut traffic by an order of magnitude on homogeneous inventories.
Back off and surface partial UI when the API signals a limit; don’t retry aggressively.

You can start with the Starter plan ($19/mo), and every plan includes a 7-day free trial via Register. Learn more about the platform at vehicles-api.com.

Designing your UI for real-world data

Badge the scope: If match is partial, show “Model-year rating (not trim-specific)” in a tooltip or footnote.
Rollup rules: If overall is null, display per-test stars only; don’t calculate your own composite.
Accessibility: Represent stars in both icon and numeric form (e.g., “Front driver: 5/5”).
No ratings: If an error indicates US coverage only for a non-US VIN, omit the widget rather than showing zeros.

Integration order with other Vehicle API features

VIN decoding first: Use the VIN decode endpoint to standardize year/make/model/trim and engine details; decoding works worldwide, with fullest coverage for US-market vehicles.
Safety stack: In US-market contexts, combine NCAP stars with recalls and owner complaints, all of which are official US datasets matched at the make + model + year level.
Non-US flows: For Dutch registrations (RDW), build a plate-first flow for specs and omit NCAP ratings; Dutch plates will not include a VIN.

Error handling patterns you can copy

Recommended flow:

Call /vin/safety-ratings with the VIN.
If status === "error" and error.code === "coverage_us_only" (HTTP 422), hide the ratings widget and optionally show a region-specific note.
If status === "success", render all non-null star fields. Leave nulls blank or labeled “Not published by NHTSA.”

Always log error.code and error.message for observability. Since the response is consistently enveloped, you can standardize error handling across endpoints.

MCP server for agents and tools

If you are building AI agents or internal CLI utilities, the same data is available via a Model Context Protocol (MCP) server at MCP. This lets you plug NCAP ratings, recalls, and complaint data into your agent runtime with a stable tool interface.

Testing checklist

Use the control VIN 1HGCM82633A004352 to verify end-to-end connectivity and envelope parsing.
Confirm your UI tolerates null for overall, front.overall, and side.overall.
Simulate a non-US VIN in staging and ensure you handle coverage_us_only errors and HTTP 422 gracefully.
Cache per make+model+year. Verify multiple VINs reuse the same cached stars.

Production tips

Observability: Log vin, coverage, match, and presence/absence of null star fields for analytics.
Null-aware metrics: Track null rate by model year—older models may have more nulls for “overall.”
UI resilience: Soft-fail the ratings component; never block rendering of the rest of the vehicle details.

FAQ

Does the NCAP Crash Ratings endpoint work outside the US?
No. NCAP ratings are US-market only. For a valid non-US VIN, this endpoint returns an error with code coverage_us_only (HTTP 422). You can still decode the VIN worldwide and access other data where available.

Why are some fields null, like overall?
NHTSA does not publish an overall rating for all configurations or years. When not available, fields such as overall, front.overall, or side.overall can be null. Display per-test stars that are present and label missing values as “not published.”

How exact are the matches?
Ratings are matched by make + model + year. The match field (e.g., partial) clarifies specificity. Treat ratings as applicable to the model year rather than a precise trim unless the response indicates otherwise.

Can I get this via an MCP tool instead of HTTP?
Yes. Use the Vehicle API MCP server at MCP to integrate ratings into agents or automation without managing HTTP glue code.

What are the rate limits and monthly quota?
They vary by plan. Check your dashboard and the Documentation. Use caching keyed by year/make/model to reduce calls.

Ship your NCAP integration today. Start the 7‑day free trial and get an API key: Register. Learn more about the platform at vehicles-api.com.

Topics

NCAP Crash Ratings API API development guide crash-test data integration automotive API solutions vehicle safety ratings API