VehiclesDB

Getting Started

From messy vehicle string to canonical id in five minutes.

VehiclesDB is the open catalogue of what vehicles exist: 14,000+ models across 850+ makes and 6 kinds (cars, motorcycles, mopeds, vans, trucks, buses), reconciled from the official registers of 18 countries, versioned, and free forever under CC-BY 4.0. On top of the open data sits a hosted API for the hard part: turning messy real-world vehicle strings into canonical ids.

There are three ways in — pick the one that fits.

1. The open data (free, no account)

Grab the latest release straight from the CDN:

curl -sL https://cdn.jsdelivr.net/gh/vehiclesdb/vehiclesdb@latest/dist/vehicles.json

Also available as CSV, Parquet, and a single-file SQLite database — see the vehiclesdb repo for every format, the schema contract, and the per-source licensing notes. Attribution ("Vehicle data by VehiclesDB") is a condition of the license, not a courtesy.

2. The Ruby gem (free, offline, zero config)

# Gemfile
gem "vehicles"  # or `gem "vehiclesdb"` — same module, VehiclesDB constant

The dataset ships inside the gem — no API keys, no network:

Vehicles.find("vw golf")                  # => #<Vehicles::Model "Volkswagen Golf">
Vehicles.makes(kind: :motorcycle)         # dropdown-ready make lists
Vehicles.top_models(kind: :car, country: :de, limit: 10)
Vehicles.plates(:nl)                      # license-plate formats + validation
model.former_ids                          # append-only id migration aliases

It also bundles validators for your models, dropdown helpers for your forms, and an MCP server (vehicles-mcp) so agents can query the catalog. Docs: github.com/vehiclesdb/vehicles.

3. The hosted API (the resolver — free tier included)

The API does what the offline snapshot can't: resolution — registry rows, insurance policy lines, marketplace titles in; canonical ids with confidence and a machine-readable audit trail out.

Step 1 — get a key. Create an account, then mint your private key at Settings → API keys. Private keys look like vdb_sk_…. Every account starts with 100 free credits, once, with no card and no trial clock.

Step 2 — resolve something messy:

curl -s -X POST https://vehiclesdb.com/api/v1/resolve \
  -H "Authorization: Bearer vdb_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "MERCEDES-BENZ | SPRINTER", "kind_hint": "van"}'

{
  "match": {
    "id": "van/mercedes-benz/sprinter",
    "name": "Sprinter",
    "make": { "id": "mercedes-benz", "name": "Mercedes-Benz" },
    "kind": "van",
    "confidence": 0.97,
    "method": "fold"
  },
  "alternates": [
    { "id": "bus/mercedes-benz/sprinter", "confidence": 0.45 },
    { "id": "truck/mercedes-benz/sprinter", "confidence": 0.45 }
  ],
  "resolved_via": ["fold:sprinter→sprinter", "kind_hint:van"],
  "dataset_version": "2026.10.3"
}

resolved_via is the audit trail — log it next to your stored id and every resolution is explainable later. When we can't resolve honestly, you get "match": null plus ranked candidates — never a guess past the confidence floor.

Step 3 — go deeper on a record:

# The full record: identity + production runs, variants, links, make facts
curl -s https://vehiclesdb.com/api/v1/vehicles/van/mercedes-benz/sprinter/full \
  -H "Authorization: Bearer vdb_sk_YOUR_KEY"

# Rendered imagery: studio-style cutouts, three sizes, honest color fallback
curl -s "https://vehiclesdb.com/api/v1/vehicles/car/renault/clio/images?color=blue" \
  -H "Authorization: Bearer vdb_sk_YOUR_KEY"

The complete contract — every parameter, response shape, and error — lives in the interactive API reference, generated from the same code that serves the requests.

Credits, plans, and running out

The free key check and dropdown endpoints spend nothing. Resolve, images, and plate matching cost 1 credit; a full vehicle record costs 2; a jurisdiction's whole plate corpus costs 5. Malformed requests and unknown ids are free. An honest "match": null from the resolver still costs 1 because the resolution work ran either way.

Running low? Billing shows your live balance and recent usage and sells instant top-up packs. Paid plans refill monthly; unused subscription credits expire at the refill, while credit packs bought outright never expire. If your wallet empties, the API answers 402 with the self-serve options — no overage charges or surprise bills.

The data itself

Every record is corroborated by at least two independent official sources (or one with a fleet count no typo could produce). Ids are stable forever — renames leave former_ids behind, nothing is silently deleted. The dataset version is part of every API response, and fresh data lands monthly. How it's all built, measured, and audited: the public QA program.