Getting Started

VehiclesDB is the open catalogue of what vehicles exist: 15,626 models across 856 makes and 6 kinds (cars, motorcycles, mopeds, vans, trucks, buses), reconciled from the official registers of 14 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 a key at Settings → API keys. Keys look like vdb_… and every account starts with 1,000 free credits a month (1 credit = 1 request).

Step 2 — resolve something messy:

curl -s -X POST https://vehiclesdb.com/v1/resolve \
  -H "Authorization: Bearer vdb_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.08.0"
}

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/v1/vehicles/van/mercedes-benz/sprinter/full \
  -H "Authorization: Bearer vdb_YOUR_KEY"

# Rendered imagery: studio-style cutouts, three sizes, honest color fallback
curl -s "https://vehiclesdb.com/v1/vehicles/car/renault/clio/images?color=blue" \
  -H "Authorization: Bearer vdb_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

Every served response spends one credit; malformed requests and unknown ids are free. Running low? Billing shows your live balance and recent usage, sells instant top-up packs, and paid plans (50k–500k credits/month, unused credits roll over) are on the pricing page. If your wallet empties, the API answers 402 with the self-serve options — no overage charges, no surprise bills, ever.

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.