Rollover Rating API

You’re building a pricing, quoting, or risk model and need a trustworthy way to retrieve the NHTSA rollover star rating for a vehicle from a VIN. By the end of this guide, you’ll be able to query the Vehicle API’s safety ratings endpoint, read the rollover field, handle partial matches and nulls, and ship production-grade error handling and caching around it.

What the Rollover Rating Represents and When to Use It

The rollover rating is part of NHTSA’s NCAP star ratings and indicates the relative risk of a vehicle rolling over in a single-vehicle crash. It’s an integer star value (1–5, where 5 is better). For many finance and insurance workflows, this metric contributes to:

• Risk scoring and underwriting inputs
• Residual value modeling and remarketing guardrails
• Market segmentation for quotes or rate cards
• Safety-feature–weighted decisioning in fleet or lending policies

Vehicle API exposes the rollover rating alongside other NCAP fields via a single endpoint. Coverage is strictly US-market for NCAP data and is matched by make + model + year (not by VIN-specific crash tests). For non-US-market vehicles, expect an error indicating US-only coverage on this endpoint.

The Endpoint You’ll Call

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

Endpoint: GET /vin/safety-ratings

Authentication: Pass X-API-Key: YOUR_API_KEY (Authorization: Bearer YOUR_API_KEY also works). The response is an envelope that always includes status and source, plus either data or error with code and message. The rollover rating is returned in data.rollover when available.

Official cURL Example

Copy, paste, and run. This request uses the control VIN (a 2003 Honda Accord) to demonstrate a real response structure; do not treat it as your user’s car.

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

Official JSON Response

This is the official example. It shows a US-market match with a rollover rating of 4 stars. Notice that some aggregate fields can be null if NHTSA did not publish them.

{
"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 Actually Use

• status: "success" or "error". Check this first.
• source: "nhtsa" for NCAP-derived data.
• data.vin: Echo of the VIN you provided. Useful for logging and cache keys.
• data.coverage: "us" when ratings are available for the US market. Ratings are US-market only.
• data.match: "partial" indicates the match is make + model + year (typical for NCAP). Expect this value on ratings lookups.
• data.vehicle_description: Human-readable descriptor of the vehicle family NHTSA matched (e.g., body style).
• data.rollover: Integer 1–5. This is the primary field for risk and pricing models on this endpoint.
• data.front, data.side: Nested objects with driver and passenger stars. Helpful for safety indexes even when you only need rollover.
• data.overall, data.front.overall, data.side.overall: Can be null if not published by NHTSA. Build null-safe logic.
• data.nhtsa_vehicle_id: NHTSA’s internal vehicle ID for the tested configuration.

JavaScript Example: Fetch and Read the Rollover Rating

This sample calls the same endpoint, checks the envelope, handles nulls, and extracts the rollover rating with minimal assumptions.

async function getRolloverRating(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'
}
});

// Basic transport-level error handling
if (!res.ok) {
// Non-2xx response. The body will still be an envelope with error fields.
const errBody = await res.json().catch(() => ({}));
const code = errBody?.error?.code || `http_${res.status}`;
const message = errBody?.error?.message || 'Request failed';
throw new Error(`${code}: ${message}`);
}

const body = await res.json();

// Envelope status check
if (body.status !== 'success' || !body.data) {
const code = body?.error?.code || 'unknown_error';
const message = body?.error?.message || 'Unexpected response';
throw new Error(`${code}: ${message}`);
}

const data = body.data;

// Rollover can be null if not published; treat missing as undefined
const rollover = data.rollover ?? null;

return {
vin: data.vin || vin,
coverage: data.coverage,
match: data.match,
description: data.vehicle_description || null,
rollover, // 1–5 or null
frontDriver: data.front?.driver ?? null,
frontPassenger: data.front?.passenger ?? null,
sideDriver: data.side?.driver ?? null,
sidePassenger: data.side?.passenger ?? null,
nhtsaVehicleId: data.nhtsa_vehicle_id ?? null
};
}

// Example usage:
getRolloverRating('1HGCM82633A004352')
.then(console.log)
.catch(console.error);

How Matching Works and Why match = "partial"

NCAP ratings are not produced for each individual VIN. Instead, NHTSA tests representative configurations and publishes ratings by make, model, and year (and sometimes body style or restraint configuration). As a result, the API will return match: "partial" for safety ratings, indicating the rating corresponds to the tested vehicle family that best maps to the supplied VIN.

Practical implications:

• Cache by VIN, year, make, and model, not by per-trim expectation. The same VIN should consistently retrieve the same family rating until NHTSA updates its data.
• Do not assume a fully VIN-specific test: display language like “NHTSA rating for this model year” where applicable.
• If you need global VIN coverage, remember that NCAP ratings are US-market only. Non-US VINs will not return ratings here.

Coverage and Scope You Should Rely On

• VIN decoding: Worldwide, with the richest detail for US-market vehicles.
• Safety ratings (this endpoint), recalls, and owner complaints: US-market only, matched by make + model + year.
• Dutch plate lookups: From RDW open data; plates do not include a VIN.
• This is not a vehicle history report. It does not include title, accident, lien, or ownership history.

Error Handling and Common Failure Modes

All responses use a consistent envelope. When an error occurs, you get:

• status: "error"
• error.code: A machine-friendly string (e.g., coverage_us_only)
• error.message: A human-readable explanation

On this endpoint specifically:

• Non-US VINs: Expect HTTP 422 with error.code coverage_us_only. Handle this by short-circuiting to “no US NCAP data”.
• Missing or invalid VIN: You’ll receive an error envelope; validate VIN format before calling to avoid unnecessary requests.
• Null fields: overall and some aggregates may be null if NHTSA didn’t publish them. Always null-check before using.

Tip: Log the response source field. For ratings it will be "nhtsa", which helps trace downstream decisions in audits and underwriting pipelines.

Rate Limits, Quotas, and Caching

Each plan has a monthly quota and rate limits. Exact numbers can vary by plan; check your dashboard and the Documentation for the latest details. The Starter plan is $19/month and all plans include a 7-day free trial.

Recommended caching strategy:

• Cache successful safety-ratings responses keyed by VIN and by the derived make+model+year from your decode step. Ratings are stable and updated only when NHTSA publishes new data.
• Honor null values: cache them too to avoid hammering the endpoint for vehicles without published aggregates.
• Set a conservative TTL (e.g., weekly or monthly) since NCAP data does not change frequently. Adjust based on your operational needs.

Building a Robust Integration in Production

Authentication

• Preferred: X-API-Key header. Authorization: Bearer also works if your platform standardizes on that.
• Never embed the key in query parameters or client-side code that can be inspected in browsers.

Input Validation

• Verify VIN length and character set before calling to cut down on failed requests.
• Use a decode step to get year/make/model if you plan to build composite caches or display language around the matched configuration.

Null-safe UI/Modeling

• overall may be null; do not assume a composite exists. If you need a single score, you can rely directly on rollover or build your own weighted index from the returned sub-scores that are not null.
• Present rollover clearly as a 1–5 star metric; do not extrapolate decimals if not provided.

Auditing and Explainability

• Log source and nhtsa_vehicle_id alongside the VIN for traceability in pricing and risk engines.
• Persist the exact response payload (or a normalized subset) for deterministic recalculations and compliance reviews.

Understanding the Response Structure

Why the Rollover Field Matters in Finance and Insurance Apps

• Underwriting: A lower rollover star rating can indicate higher rollover risk, influencing premiums or collateral requirements.
• Loss Cost Modeling: Combine rollover with frontal and side stars to build an internal safety index for expected loss severities.
• Residual Value and Remarketing: Rollover and other safety metrics can be features in price elasticity and time-to-sale models.
• Portfolio Risk Controls: Gate acquisitions or loan approvals by a minimum rollover threshold in high-volatility markets.

Because ratings are matched by make + model + year, ensure your pricing and risk logic reflects family-level safety attributes rather than VIN-specific crash results.

MCP Server Access for Agentic Workflows

If you’re building AI agents, you can access the same data via the MCP server at MCP. Use it to enable tool-aware agents that can look up rollover ratings and other safety fields on demand with consistent envelopes and error codes.

Operational Tips That Save Time

• Display clarity: Label as “NHTSA rollover star rating” and specify it’s US-market coverage matched by make/model/year.
• Null handling: Prefer “Not published” UI text over 0 or N/A for aggregate overall fields when null.
• Resilience: If you process large VIN batches, parallelize with rate-limit awareness and retry only idempotent 5xx failures.
• Logging: Log request ID (your own), VIN, source, and nhtsa_vehicle_id so disputes can be resolved quickly.

Security and Compliance Notes

• Keep API keys server-side. Do not bundle them in public apps.
• Cache responsibly and purge on data policy changes or account closure.
• This endpoint exposes no PII; it returns public safety data matched to vehicle families.

Getting Started

Create an account to get your key and start calling the endpoint. Every plan, including Starter ($19/month), includes a 7-day free trial. See details in the Documentation and register here: Register. For AI agent access, see the MCP server.

FAQ

Does the rollover rating apply to vehicles outside the US?
No. NCAP ratings in this endpoint are US-market only. If you submit a valid non-US VIN, you’ll receive a 422 error with code coverage_us_only.

Why is overall null when rollover has a value?
NHTSA does not always publish an overall composite. The API reflects published fields; treat nulls as “not published” and avoid synthesizing values.

Is the rating VIN-specific?
No. Ratings are matched by make + model + year (and sometimes body style), which is why match is often "partial". Cache and display accordingly.

What’s the response envelope format on errors?
status will be "error" and the payload includes error.code and error.message. Handle these deterministically; for non-US VINs, detect coverage_us_only and skip US-only safety logic.

Can I call this from a browser?
Use a backend proxy. Do not expose your API key in client-side code. Server-side calls with X-API-Key or Bearer auth are supported.

Ship your rollover-rating integration today. Explore the endpoint behavior in the Documentation and start your 7-day free trial by creating an account: Register.