Vehicle Analytics & Data API

Query a vehicle's full analytical profile by VIN or license plate: rich normalized fields, computed health and risk scores, mileage and ownership time-series, and market comparatives. Bearer authentication, configurable rate limiting.

https://api.vinanalyser.com/v1

Request access View endpoints

Quick Start Authentication Endpoints Response Schema Error Codes Rate Limiting

Quick Start

Generate an API key

Create an account in the dashboard and generate a key pair (sandbox + production). Sandbox keys return realistic sample analyses without consuming quota.

Send a request

Authenticate with the Authorization: Bearer header and your X-Analytics-Key, then POST to /v1/analyses to run your first analysis and inspect the response schema.

Parse the analytics

Responses are normalized JSON exposing health_score, risk_index, the metrics block and a mileage timeseries. Read the scores for the computed indices and metrics for the underlying signals.

Authentication

Every request must carry an Authorization header with a valid Bearer token plus your X-Analytics-Key header. Keys expire after 12 months and rotate without downtime from the dashboard. Each key is scoped to a data tier that governs which analytics fields are returned.

Example request

curl -X GET \
  https://api.vinanalyser.com/v1/analyses/an_7c3d20 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Analytics-Key: YOUR_ANALYTICS_KEY" \
  -H "Content-Type: application/json"

Bearer token

Pass your API key in the Authorization header as a Bearer token, alongside the X-Analytics-Key header that identifies your analytics workspace. Generate and rotate keys from your dashboard without downtime; the key's tier determines scoring and time-series access.

Never expose API keys in client-side code or query parameters. Use environment variables and a server-side proxy.

Endpoints

Five endpoints in v1. All accept and return JSON. POST requests require a valid JSON body. Analytics depth (scores, comparatives, series) scales with the depth parameter and the key's data tier.

POST/v1/analyses

Run an analysis

Runs a full vehicle analysis: aggregated history, computed health_score and risk_index, ownership and mileage time-series, and market comparatives. Returns an analysis object identified by an an_ prefix.

Name	Type	Required	Description
`vin`	string	Conditional	17-character VIN. Required if license_plate is not provided
`license_plate`	string	Conditional	License plate number. Required if vin is not provided
`depth`	string	No	Analysis depth: standard (default) or full, controlling scores, comparatives and series

By VIN

curl -X POST https://api.vinanalyser.com/v1/analyses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Analytics-Key: YOUR_ANALYTICS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vin": "WBA3A5G59DNP26082", "depth": "full"}'

By license plate

curl -X POST https://api.vinanalyser.com/v1/analyses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Analytics-Key: YOUR_ANALYTICS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"license_plate": "AB-123-CD", "depth": "standard"}'

GET/v1/analyses/{analysis_id}

Retrieve an analysis

Fetches a previously computed analysis by its analysis_id, returning the full object with scores, metrics, timeseries and the resolved data_points count.

Name	Type	Required	Description
`analysis_id`	string	Yes	Analysis identifier, prefixed an_ (path parameter)

curl -X GET https://api.vinanalyser.com/v1/analyses/an_7c3d20 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Analytics-Key: YOUR_ANALYTICS_KEY"

GET/v1/analyses/{analysis_id}/timeseries

Mileage & ownership time-series

Returns the dated time-series powering an analysis: odometer readings over time and ownership changes, ready to plot trend curves or detect rollbacks.

Name	Type	Required	Description
`analysis_id`	string	Yes	Analysis identifier, prefixed an_ (path parameter)
`metric`	string	No	Series to return: mileage (default) or ownership

curl -X GET "https://api.vinanalyser.com/v1/analyses/an_7c3d20/timeseries?metric=mileage" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Analytics-Key: YOUR_ANALYTICS_KEY"

GET/v1/vehicles/{vin}/score

Quick score

Score-only endpoint: returns the latest health_score and risk_index for a VIN without running a full analysis, ideal for fast inventory triage.

Name	Type	Required	Description
`vin`	string	Yes	17-character VIN (path parameter)

curl -X GET https://api.vinanalyser.com/v1/vehicles/WBA3A5G59DNP26082/score \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Analytics-Key: YOUR_ANALYTICS_KEY"

POST/v1/analyses/batch

Batch analytics

Submits an array of VINs or license plates for parallel analysis, ideal for scoring an inventory or building comparative datasets.

Name	Type	Required	Description
`identifiers`	array	Yes	Array of VINs or license plates (max 100 per request)
`depth`	string	No	Analysis depth applied to every item: standard (default) or full

curl -X POST https://api.vinanalyser.com/v1/analyses/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Analytics-Key: YOUR_ANALYTICS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identifiers": ["WBA3A5G59DNP26082", "AB-123-CD"], "depth": "standard"}'

Response Schema

Every analysis returns a uniform JSON object. Top-level fields carry the analysis_id and computed scores, the vehicle and metrics blocks hold the signals, timeseries the dated points, and meta the analysis depth.

200 OK

{
  "analysis_id": "an_7c3d20",
  "vin": "WBA3A5G59DNP26082",
  "scored_at": "2026-03-12T10:04:00Z",
  "health_score": 8.6,
  "risk_index": 0.21,
  "vehicle": {
    "make": "BMW",
    "model": "320d",
    "year": 2019
  },
  "metrics": {
    "mileage_trend": "consistent",
    "accident_severity": "none",
    "ownership_stability": 0.92,
    "market_value": {
      "value": 18400,
      "unit": "EUR"
    }
  },
  "timeseries": [
    { "date": "2021-03", "mileage": 12000 },
    { "date": "2026-01", "mileage": 142350 }
  ],
  "data_points": 8200,
  "meta": {
    "depth": "full"
  }
}

Field reference

analysis_idstring

Unique identifier of the analysis, prefixed an_.

vinstring

The analysed Vehicle Identification Number, used as the analysis key.

scored_atstring

ISO 8601 timestamp at which the scores were computed.

health_scorefloat

Computed overall vehicle health score, from 0 to 10.

risk_indexfloat

Computed risk index from 0 (low) to 1 (high), aggregating history signals.

vehicleobject

Identified make, model and year used to baseline the analysis.

metrics.mileage_trendstring

Mileage trend signal: consistent, irregular or suspicious.

metrics.ownership_stabilityfloat

Ownership stability score from 0 to 1, higher meaning fewer transfers.

metrics.market_valueobject

Estimated market value with its currency unit.

timeseriesarray

Dated mileage points powering the trend curves.

data_pointsinteger

Total number of data points resolved for this analysis.

Error Codes

The API returns standard HTTP codes with their standard reason phrases. The body includes an error object with code, message and detail fields to help you debug your integration.

400

Bad Request

The request body or parameters are malformed or missing required fields.

401

Unauthorized

The API key is missing, invalid, or has been revoked.

403

Forbidden

The API key's data tier does not grant access to this endpoint or analytics block.

404

Not Found

The requested resource (analysis, vehicle) was not found.

429

Too Many Requests

Rate limit exceeded. Inspect the X-Analytics-RateLimit headers and retry after the reset window.

500

Server Error

An internal error occurred. Retry the request or contact support if it persists.

Error response

{
  "status": "error",
  "error": {
    "code": 401,
    "message": "Unauthorized",
    "detail": "The provided API key is invalid
               or has expired."
  }
}

Rate Limiting

Throttling is applied per API key with a sliding-window algorithm. Quotas scale with the data tier. Every response carries real-time counters in the X-Analytics-RateLimit headers.

300Requests / min

10,000Requests / day

20Concurrent

Every API response includes X-Analytics-RateLimit headers to help you track your usage in real time.

X-Analytics-RateLimit-LimitMaximum requests allowed per window.

X-Analytics-RateLimit-RemainingRequests remaining in the current window.

X-Analytics-RateLimit-ResetUnix timestamp when the rate limit resets.

Start building today

Request sandbox access to test the analytics API under real conditions. Moving to production requires no code changes.

Request access View endpoints