Developers building transportation apps often need a reliable, normalized “frontal crash rating” for a vehicle to power listings, underwriting, and safety UX. By the end of this guide, you will use Vehicle API’s safety ratings endpoint to fetch the NCAP frontal driver and passenger star ratings for a VIN, understand the response envelope and nulls, handle US-market coverage constraints, and ship production-grade error handling and caching.
What this endpoint delivers and when to use it
Vehicle API exposes US NHTSA NCAP crash-test ratings (frontal, side, rollover) for vehicles matched by decoded make + model + year. Use it to:
- Surface “front” crash-test stars (driver and passenger) on marketplace VDPs and dealer SRPs.
- Power underwriting rules and premium adjustments with a normalized 1–5 star scale.
- Drive agent reasoning: include front.driver and front.passenger in your prompts via the MCP server.
Coverage is US-market only for NCAP ratings. If you query a valid non-US VIN against this endpoint, you receive a 422 coverage_us_only error. Ratings are matched by make + model + year derived from the VIN decode, not per-VIN crash tests. The “front” object is your primary target for frontal crash stars.
Endpoint and authentication
Base URL: https://vehicles-api.com/api/v1
Endpoint: GET /vin/safety-ratings
Authentication headers:
- X-API-Key: YOUR_API_KEY
- Authorization: Bearer YOUR_API_KEY (also supported)
You can register for a 7-day free trial at Register. Learn more in the Documentation. The product homepage is vehicles-api.com.
Official sample: cURL and JSON
Use the official example below to validate your wiring. It uses the control VIN 1HGCM82633A004352 (a 2003 Honda Accord). This is not your user’s car—do not hardcode it outside tests.
curl "https://vehicles-api.com/api/v1/vin/safety-ratings?vin=1HGCM82633A004352" -H "X-API-Key: YOUR_API_KEY"{
"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
}
}Read the “front” ratings you actually need
Focus on the “front” object for Frontal Crash Rating use cases:
- front.driver: integer star rating (1–5) for the driver in a frontal crash.
- front.passenger: integer star rating (1–5) for the front passenger.
- front.overall: can be null if NHTSA did not publish an overall frontal rating for that make/model/year.
Additional fields you will likely use in UI and data quality flows:
- overall: overall NCAP vehicle rating, can be null. Do not assume it exists.
- side.driver, side.passenger, rollover: sibling ratings you may choose to display but are not required for a Frontal Crash Rating feature.
- coverage: “us” when US-market ratings were available.
- match: matching confidence based on make + model + year. “partial” is common when NHTSA publishes by body style; handle it in your UX.
- vehicle_description: human-readable descriptor to display alongside stars.
- nhtsa_vehicle_id: NHTSA’s internal identifier, useful if you link out or reconcile datasets.
Response envelope:
- status: “success” for successful lookups. On failures, “error”.
- source: “nhtsa” for this endpoint.
- data: object containing the ratings payload, as shown above.
JavaScript example: fetch and extract frontal stars
This Node.js or browser-friendly example hits the same endpoint, reads front.driver and front.passenger, and normalizes nulls.
async function getFrontalRatings(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'
// Authorization: 'Bearer YOUR_API_KEY' also works
}
});
// Basic error guard; see the Error handling section for more details.
if (!res.ok) {
// For non-US VINs on this endpoint, expect HTTP 422 with code coverage_us_only.
const err = await res.json().catch(() => ({}));
throw new Error(`Vehicle API error (${res.status}): ${JSON.stringify(err)}`);
}
const body = await res.json();
if (body.status !== 'success' || !body.data) {
throw new Error('Vehicle API returned a non-success status envelope.');
}
const data = body.data;
const front = data.front || {};
// Ratings are 1–5 stars; overall may be null. Defensively read driver/passenger.
return {
vin: data.vin,
coverage: data.coverage,
match: data.match,
vehicleDescription: data.vehicle_description,
driverStars: front.driver ?? null,
passengerStars: front.passenger ?? null,
frontalOverall: front.overall ?? null
};
}
// Example usage with the control VIN for tests:
getFrontalRatings('1HGCM82633A004352')
.then(console.log)
.catch(console.error);Request and response details you should plan for
Coverage and matching
- US-market only: The safety-ratings endpoint returns NCAP crash-test data from NHTSA for US-market vehicles.
- Non-US VINs: A valid non-US VIN yields 422 coverage_us_only for this endpoint.
- VIN decoding: The system decodes the VIN (worldwide decoding via NHTSA vPIC) and matches ratings by make + model + year. That means multiple VINs for the same MMY will share the same ratings object.
- Match field: match may be “partial” when the vehicle’s exact sub-configuration or body style has nuances relative to NHTSA’s published group. Always check match to inform consumers about precision.
Null fields
- overall (vehicle): may be null if NHTSA did not publish an overall rating for that MMY.
- front.overall: may be null independent of front.driver and front.passenger, which are often populated.
- Defensive parsing: Use null checks and default behaviors in UI (e.g., display “Not rated” for nulls).
Response envelope and errors
- Envelope: Every response is wrapped with status, source, and data on success.
- Errors: On error, status is “error” with error.code and error.message. For this endpoint, the notable specific code is coverage_us_only (HTTP 422) when ratings are US-only but the VIN decodes as non-US.
- Other errors: Authentication, authorization, and quota issues follow standard patterns; consult the Documentation for the current list and handling strategies.
Rate limits, monthly quota, and retries
- Plans include a 7-day free trial, starting at Starter ($19/mo). Exact rate limits and monthly quotas vary by plan; verify in the Documentation and your dashboard.
- Retries: Use exponential backoff for transient network or 5xx responses. Do not retry 4xx validation errors (e.g., coverage_us_only).
- Caching: Since ratings are matched by MMY and change infrequently, cache results per MMY (or per the response’s nhtsa_vehicle_id) for a prolonged period. Revalidation cadence depends on your compliance needs; weekly or monthly is common.
Production integration checklist
- Authentication: Send X-API-Key: YOUR_API_KEY. Authorization: Bearer YOUR_API_KEY is also supported.
- VIN input: Collect a 17-character VIN. Validate format client-side to reduce waste.
- Endpoint: GET https://vehicles-api.com/api/v1/vin/safety-ratings?vin=VIN_VALUE
- Parse: Read data.front.driver and data.front.passenger as integers (1–5). Treat null as “Not rated”.
- Label: Display vehicle_description with the stars to improve user clarity.
- Coverage: If error.code is coverage_us_only, suppress stars and message users that US NCAP is unavailable for this VIN.
- Nulls: Avoid averaging or inferring an overall when overall or front.overall are null.
- Caching: Cache the full response, including nhtsa_vehicle_id and match, keyed by MMY or nhtsa_vehicle_id to reduce latency and cost.
- Monitoring: Log match to identify “partial” cases and verify UX and underwriting rules behave as intended.
Data sources and scope clarity
Source: NHTSA NCAP frontal, side, and rollover star ratings for US-market vehicles. These are official US safety tests. Ratings are not per-VIN crash tests; they’re mapped by MMY after VIN decoding.
What this is not: This is not a vehicle history report. No title, accident, or ownership history is included. Dutch plates from RDW are supported by Vehicle API for plate lookups, but they never include a VIN and are not part of NCAP ratings. For broader vehicle data and agents, see vehicles-api.com and the MCP server.
UI and data modeling patterns for frontal ratings
- Store fields: vin, coverage, match, vehicle_description, front.driver, front.passenger, front.overall, overall, side, rollover, nhtsa_vehicle_id.
- Display logic:
- Frontal stars: show driver and passenger separately. If one is null, show the other; do not synthesize a value.
- Badges: indicate “US NCAP” or “Not available outside US market” based on coverage and error handling.
- Tooltips: include vehicle_description and match to set context for users.
- Aggregation: If you must expose a single “frontal rating” value, pick a deterministic rule (e.g., min(driver, passenger)) but clearly label the rule. Many teams choose to show both values instead.
- Search filters: Index vehicles by minimum driver/passenger stars to enable safety-based filtering.
Error handling patterns
- Non-US VINs: On 422 coverage_us_only, hide NCAP sections and provide a neutral message (“US NCAP ratings are not available for this VIN”).
- Null fields: Present “Not rated” strings; do not gray out the entire safety panel if some subfields exist.
- Envelope checks: Always check status === "success" before reading data. On status === "error", read error.code and error.message for logs and UX.
- Timeouts and retries: Implement timeouts and safe retries for network faults; avoid retry storms by respecting backoff and idempotency.
Caching strategy
- Keying: Since ratings are matched by MMY and identified via nhtsa_vehicle_id, cache by nhtsa_vehicle_id or MMY tuple (make, model, year) rather than VIN to maximize reuse.
- TTL: Ratings change infrequently. Many teams refresh monthly; some weekly during development. Confirm any regulatory needs with your stakeholders.
- Nulls in cache: Cache nulls too, to avoid refetching permanently absent fields like overall or front.overall for legacy models.
- Prewarming: If your workflow decodes VINs in bulk, prewarm the ratings cache upon decode completion to reduce user-perceived latency in downstream views.
MCP and agents
If your transportation product includes an AI assistant, the same ratings are available from the Vehicle API MCP server at MCP. Agents can retrieve the “front” object and reason over driver vs passenger stars. Keep the same US-market scope in your prompts and ensure agents check coverage and match before making safety recommendations.
Security, testing, and operations
- Secrets: Keep YOUR_API_KEY in environment variables or a secret manager.
- Testing: Use the control VIN 1HGCM82633A004352 in CI to assert envelope shape, null handling, and extraction of front.driver and front.passenger.
- Observability: Log VIN, coverage, match, nhtsa_vehicle_id, and timing. Alert on elevated error rates or spikes in coverage_us_only to track user mix by region.
FAQ
Does the Frontal Crash Rating cover non-US vehicles?
No. NCAP crash ratings in this endpoint are US-market only. A valid non-US VIN returns an HTTP 422 with error.code coverage_us_only.
Are frontal ratings per VIN?
No. Ratings are matched by decoded make + model + year from the VIN. Multiple VINs for the same MMY will share the same ratings object.
Why are some overall fields null?
NHTSA does not publish overall values for all vehicles or subtests. overall and front.overall can be null even when front.driver and front.passenger exist. Handle nulls gracefully.
What are the rate limits and monthly quotas?
They depend on your plan. Check the dashboard and Documentation for current limits. All plans include a 7-day free trial.
Can I combine this with Dutch plate data?
Yes, Vehicle API supports Dutch plates from RDW open data, but plates never include a VIN and NCAP ratings remain US-only. Use them in parallel as needed within your transportation workflows.
Start integrating the Frontal Crash Rating into your transportation product now. Get an API key with the 7-day free trial at Register, and keep the docs handy at Documentation. For agent-based integrations, see MCP and explore more at vehicles-api.com.
