🚗 `vehicles` – Car makes & models for your Rails app

[!TIP] 🚀 Ship your next Rails app 10x faster! I've built RailsFast, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go check it out!

vehicles gives your Rails app a clean, curated list of vehicle makes and models — 18.5k models across 900+ makes: cars, motorcycles, mopeds, vans, trucks and buses, reconciled from official registers of 14 countries — ready for dropdowns, search, and validation. No API keys, no database table, no migration — it works fully offline the second you bundle install, because the data ships inside the gem. (Optionally, it can refresh the data without a gem upgrade.)

✨ Perfect for marketplaces, carpooling & rideshare apps, fleet tools, parking & EV-charging apps, insurance and booking forms — anywhere a user has to pick their vehicle.

Check out my other 💎 Ruby gems: usage_credits · profitable · api_keys · nondisposable · trackdown

👨‍💻 Example

Vehicles.makes
# => ["Alfa Romeo", "Audi", "BMW", "BYD", "Citroën", "Cupra", "Dacia", "Fiat", ...]

Vehicles.models("VW")              # alias-aware — "VW" just works
# => ["Golf", "Polo", "Tiguan", "Passat", "T-Roc", "ID.3", "ID.4", "T-Cross", ...]

car = Vehicles.find("vw golf")     # one fuzzy lookup, make + model in a single string
car.make                           # => "Volkswagen"
car.name                           # => "Golf"
car.full_name                      # => "Volkswagen Golf"
car.kind                           # => :car
car.body_type                      # => :hatchback
car.hatchback?                     # => true
car.global_decile                  # => 2       (top 20% worldwide, measured from registrations)
car.available_in?(:nl)             # => true    (evidence in the Dutch register)

Vehicles.top_models(kind: :car, country: :nl, limit: 5).map(&:name)
# => the most popular models, from real registration counts

…and the whole reason this gem exists — a make → model picker in two lines:

<%= form.select :make,  Vehicles.make_options,             prompt: "Make" %>
<%= form.select :model, Vehicles.model_options(@car.make), prompt: "Model" %>

That's it. A working dropdown, with zero setup and zero network calls. You can finally delete that hand-maintained MAKES = [...] constant.

Installation

Add it to your Gemfile:

gem "vehicles"

And run bundle install. That's the whole setup. No generator, no migration, no API key, no seed task — the dataset is bundled and loaded lazily into memory on first use.

[!NOTE] vehicles works in any Ruby project, not just Rails. The Rails bits (form option helpers, validators) light up automatically when Rails is present, and stay out of your way when it isn't.

The basics

Two methods cover 90% of what you need:

Vehicles.makes
# => ["Abarth", "Acura", "Alfa Romeo", ...]   (alphabetical, 900+ makes)

Vehicles.models("Toyota")
# => ["Yaris", "Corolla", "Aygo", "RAV4", "C-HR", "Prius", ...]

Make lookups are forgiving by default — case-insensitive, slug-friendly, and alias-aware, so whatever your users type tends to land:

Vehicles.models("toyota")     # case-insensitive
Vehicles.models("VW")         # => Volkswagen   (common abbreviation)
Vehicles.models("merc")       # => Mercedes-Benz
Vehicles.models("alfa-romeo") # slug form

Unknown make? You get an empty array, never an exception:

Vehicles.models("DeLorean")   # => []

Smart lookup & search

When you want the rich object instead of a plain list, ask for it:

make = Vehicles.make("Audi")     # => #<Vehicles::Make "Audi">
make.name                        # => "Audi"
make.slug                        # => "audi"
make.kinds                       # => [:car]
make.models                      # => ["A3", "A4", "Q3", "Q5", ...]
make.model("a3")                 # => #<Vehicles::Model "Audi A3">

find resolves a free-text "make + model" string into a single model — great for normalizing messy input:

Vehicles.find("vw golf")          # => #<Vehicles::Model "Volkswagen Golf">
Vehicles.find("Mercedes C Class") # => #<Vehicles::Model "Mercedes-Benz C-Class">
Vehicles.find("nope nope")        # => nil

search returns every model that matches, ranked — perfect for an autocomplete endpoint:

Vehicles.search("golf")
# => [#<Model "Volkswagen Golf">]

Vehicles.search("3")
# => [#<Model "BMW 3 Series">, #<Model "Mazda 3">, #<Model "Citroën C3">, ...]

Every Vehicles::Model reads like English and serializes cleanly:

car = Vehicles.find("seat leon")
car.make        # => "SEAT"
car.name        # => "Leon"
car.full_name   # => "SEAT Leon"
car.slug        # => "seat-leon"
car.to_h        # => { make: "SEAT", model: "Leon", slug: "seat-leon",
                #      kind: :car, body_type: :hatchback, global_decile: 2,
                #      availability: ["es", "fi", "gb", ...] }

Kinds & body types

Every vehicle is classified on two axes, so you can filter, group, and label without maintaining your own taxonomy.

kind — what sort of vehicle it is. Sourced straight from official registration data. Six kinds ship today:

Vehicles.kinds   # => [:bus, :car, :moped, :motorcycle, :truck, :van]

body_type — the sub-classification within a kind:

# cars   :hatchback :sedan :wagon :suv :mpv :coupe :convertible :roadster :pickup :van

Vehicles.find("vw tiguan").kind        # => :car
Vehicles.find("vw tiguan").body_type   # => :suv
Vehicles.find("vw tiguan").suv?        # => true   ← predicate sugar for every body_type
Vehicles.find("yamaha mt-07").kind     # => :motorcycle
Vehicles.find("yamaha mt-07").two_wheeler?  # => true  (motorcycle OR moped — picker unions)

Filter any list by either axis:

Vehicles.models("Toyota", body_type: :suv)   # => ["RAV4", "C-HR", "Yaris Cross", ...]
Vehicles.makes(kind: :car)                    # => makes that build cars
Vehicles.makes(kind: :motorcycle)             # => makes that build bikes
Vehicles.search("golf").select(&:hatchback?)

[!NOTE] body_type is honest: cars always carry one; other kinds return nil until an honest vocabulary exists for them (a truck is not a "hatchback"). The predicates just return false on nil, so your filters never crash. Market segments (supercar, city car, …) are an editorial layer that arrives with VehiclesDB.

Popularity & availability

Every model carries two open-data signals, measured from official registers (never scraped, never guessed):

car = Vehicles.find("toyota corolla")
car.global_decile      # => 1        1 = top 10% worldwide … 10; nil = unranked
car.popular?           # => true     decile ≤ 2 (and `false` when unranked — honest)
car.availability       # => ["es", "fi", "gb", ...]   countries with official evidence
car.available_in?(:th) # => true

# The most popular models — perfect for "common choices" pre-filled pickers:
Vehicles.top_models(kind: :car, country: :nl, limit: 10)   # => [Model, ...]
Vehicles.top_models(kind: :motorcycle, limit: 10).map(&:full_name)

availability means an official source evidences the model there (register, type approval, or sales reporting) — presence, not marketing history: grey imports count, because they're real vehicles on real roads.

MCP server for AI agents

The gem ships vehicles-mcp — a read-only MCP server over the bundled dataset, so your agents ground themselves in real vehicle data instead of hallucinating nameplates. No network, no keys:

{ "mcpServers": { "vehicles": { "command": "vehicles-mcp" } } }

Tools: search_makes · search_models · get_model · top_models. Works anywhere MCP does (Claude Code, Claude Desktop, Cursor, …) the moment the gem is installed.

Colors

A small canonical color palette ships with the gem — the handful of colors that cover virtually every car, plus an explicit other. It's the shared vocabulary for color dropdowns today and for color-accurate imagery from the hosted API later, so "red" means the same thing everywhere.

Vehicles.colors
# => [#<Color white "White" #F4F4F4>, #<Color black "Black" #1B1B1B>, ...]

Vehicles.color("navy")          # forgiving: synonyms, case, diacritics
# => #<Vehicles::Color blue "Blue" #27408B>
Vehicles.color("navy").slug     # => "blue"   ← the stable value you store
Vehicles.color("navy").hex      # => "#27408B" (representative swatch)

Vehicles.color_options          # => [["White", "white"], ["Black", "black"], ...]

Names are English — store the slug and localize the label in your app (the slug is also what maps to image color-variants down the line).

Rails dropdowns

The *_options helpers return [[label, value], ...] pairs, exactly what Rails' select wants:

Vehicles.make_options
# => [["Alfa Romeo", "alfa-romeo"], ["Audi", "audi"], ["BMW", "bmw"], ...]

Vehicles.model_options("audi")
# => [["A3", "a3"], ["A4", "a4"], ["Q3", "q3"], ...]

Dependent make → model picker

The whole dataset is small, so the simplest, snappiest way to wire a dependent picker is client-side: embed Vehicles.catalog once and switch the model list with no request at all — no route, no controller, no fetch.

<div data-controller="vehicle-picker"
     data-vehicle-picker-catalog-value="<%= Vehicles.catalog.to_json %>">
  <%= form.select :make,  Vehicles.makes,             { include_blank: "Make" },
        data: { vehicle_picker_target: "make", action: "change->vehicle-picker#makeChanged" } %>
  <%= form.select :model, Vehicles.models(@car&.make), { include_blank: "Model" },
        data: { vehicle_picker_target: "model" } %>
</div>

// app/javascript/controllers/vehicle_picker_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["make", "model"]
  static values  = { catalog: Object }   // { "Audi": ["A3", ...], ... }

  makeChanged() {
    const models = this.catalogValue[this.makeTarget.value] || []
    const previous = this.modelTarget.value
    this.modelTarget.replaceChildren(new Option("Model", ""))
    for (const name of models) {
      this.modelTarget.add(new Option(name, name, false, name === previous))
    }
  }
}

That's the whole picker — the gem ships the data, you keep your markup and ~12 lines of JS. (Storing slugs instead of names? Swap the selects for make_options / model_options and key the catalog by slug.)

[!TIP] Prefer a server round-trip (huge/remote dataset, or you'd rather not embed it)? It's a three-line endpoint — render json: Vehicles.models(params[:make]) — and the controller fetches that on makeChanged instead of reading the embedded catalog. Same gem API, your call.

Validations

Drop-in ActiveModel validators, so bad data never reaches your database:

class Car < ApplicationRecord
  validates :make,  vehicle_make: true                 # must be a real make
  validates :model, vehicle_model: { make: :make }     # must be a real model of that make
end

Car.new(make: "Volkswagen", model: "Golf").valid?      # => true
Car.new(make: "Volkswagen", model: "Mustang").valid?   # => false
Car.new(make: "Tesler",     model: "Model 3").valid?   # => false

They're forgiving the same way the lookups are (aliases, case, slugs), and they never raise on blank/garbage input — they just add an error.

An "Other / not in the list" escape hatch

Make/model dropdowns should never be a dead end — 18.5k models is a lot, but someone always shows up with the one car that isn't there. Turn on a first-class "Other" option and the pieces agree by construction: include_other: adds it to the picker, allow_other: lets it through validation.

# config/initializers/vehicles.rb — localize the label once (default "Other")
Vehicles.configure { |c| c.other_label = "Otro" }

<%= form.select :make,  Vehicles.makes(include_other: true),        { include_blank: "Marca" } %>
<%= form.select :model, Vehicles.models(@car.make, include_other: true), { include_blank: "Modelo" } %>

validates :make,  vehicle_make: { allow_other: true },             allow_blank: true
validates :model, vehicle_model: { make: :make, allow_other: true }, allow_blank: true

You store the label itself ("Otro") with the name-valued helpers, or the stable "other" slug with make_options / model_options. Either way Vehicles.other? recognizes it on read — matching the configured label or the canonical slug, case/diacritics-insensitively — so it's easy to skip a dataset lookup or hide it from a display string:

Vehicles.other?("Otro")     # => true   (your label)
Vehicles.other?("other")    # => true   (canonical slug, always)
Vehicles.other?("Audi")     # => false

[make, model].reject { |v| Vehicles.other?(v) }.join(" ")   # a clean display name

An unknown make (like the "Other" make itself) has no models, so Vehicles.models("Otro", include_other: true) returns just ["Otro"] — the dependent picker gets a valid choice instead of an empty select.

Recommended integration

Here's the pattern that works cleanly end to end — and a reference schema for the columns a vehicle record actually needs.

A record stores its vehicle's identity, not the reference data. Make, model, year, and color identify the car; kind and body_type (and, later, specs/images) are properties of that make+model owned by the dataset — look them up via the gem, don't duplicate them per row (they'd just drift). So the schema is small and stable:

Column	Type	Store	Example
`make`	`string`	display name	`"Volkswagen"`
`model`	`string`	display name	`"Golf"`
`year`	`integer`	the year	`2022`
`color`	`string`	a canonical color slug	`"blue"`

Everything else (kind, body_type, production years, images, …) is derived: Vehicles.model(record.make, record.model). No kind/body_type columns, no migration to add new metadata later — it lands in the dataset, not your schema.

Store the display name. The simplest, most readable thing to persist is the name itself ("Volkswagen", "Golf"). Populate the selects with the plain name lists, where the option value is the name:

<%= form.select :make,  Vehicles.makes,             { include_blank: "Make" } %>
<%= form.select :model, Vehicles.models(@car.make), { include_blank: "Model" } %>
<%= form.select :year,  (Date.current.year + 1).downto(1990).to_a, { include_blank: "Year" } %>
<%= form.select :color, Vehicles.color_options,     { include_blank: "Color" } %>

[!TIP] Use Vehicles.makes / Vehicles.models (name = value) when your column stores the display name. Use Vehicles.make_options / Vehicles.model_options (which pair [name, slug]) only when you store the slug — then read the name back with Vehicles.make(slug).name. Pick one and stay consistent.

Validate what you store — the dropdowns already constrain input, but the validators guard every other write path (imports, console, your own API):

validates :make,  vehicle_make: true,             allow_blank: true
validates :model, vehicle_model: { make: :make }, allow_blank: true
validates :color, inclusion: { in: Vehicles.colors.map(&:slug) }, allow_blank: true

Read the metadata back from a stored pair whenever you need it — kind, body type, and (with the hosted API) years/segment/image:

car = Vehicles.model(record.make, record.model)   # => Vehicles::Model | nil
car&.body_type                                      # => :hatchback
car&.suv?                                           # => false

Only accept the kinds you support. Filter every list/lookup by kind: so the picker only ever offers vehicles your app handles — and widening later (when new kind packs ship, or when you decide to accept them) is a one-word change, not a migration:

Vehicles.makes(kind: :car)                 # makes that build cars
Vehicles.models("Toyota", kind: :car)      # ...their cars only

No migration, no seed task, no API key — the data is bundled and read from memory. The whole integration is the markup above plus a 3-line endpoint for the dependent model list (see Rails dropdowns).

Country & region awareness

Vehicle availability is regional — a Vauxhall in the UK is an Opel on the continent, a Perodua exists in Malaysia and almost nowhere else. vehicles models this per country, from evidence:

Vehicles.find("perodua myvi").availability      # => ["gb", "my"]
Vehicles.find("vw golf").available_in?(:nz)     # => true
Vehicles.top_models(kind: :car, country: :es)   # country-scoped popularity

The bundled snapshot is global (official registers of 14 countries across Europe, North America, SE Asia, Oceania and Ukraine — see Where the data comes from), so the region gate accepts every region query — region: :eu callers from 0.1.x keep working unchanged:

Vehicles.makes(region: :eu)   # fine — a global snapshot covers the EU
Vehicles.region               # => :global

🔓 More with VehiclesDB

vehicles is the free, open-source SDK for VehiclesDB — a hosted API for richer vehicle data. The gem is fully standalone and always will be; pointing it at VehiclesDB is purely additive. Drop in an API key and the same objects you already use light up with more:

Vehicles.configure do |config|
  config.api_key = ENV["VEHICLESDB_API_KEY"]   # optional — unlocks hosted data
end

car = Vehicles.find("vw golf")
car.years                       # => 1974..2024            production years
car.segment                     # => :hatchback / :hot_hatch   editorial segment
car.image                       # => "https://cdn.vehiclesdb.com/volkswagen/golf.webp"
car.image(year: 2020)           # year-accurate photo
car.image(year: 2020, color: :silver)

Under the hood this is a simple provider model: a LocalProvider (the bundled data) is always available, and a HostedProvider activates only when an API key is configured. Calls prefer the hosted data when it's there and fall back to the local data otherwise — never raising, never blocking your request:

car.image     # no API key configured?  => nil   (your views just render a placeholder)
car.years     # not in the local pack yet? => nil, until you add a key or we ship it locally

So you can build your UI against the full API today, ship on the free local data, and flip on richer data later without touching your code.

Configuration

Everything has a sensible default; you can run the gem without configuring anything. When you do want to tune it:

# config/initializers/vehicles.rb
Vehicles.configure do |config|
  config.region    = :eu                          # default region for queries
  config.api_key   = ENV["VEHICLESDB_API_KEY"]    # optional hosted VehiclesDB data
  config.aliases   = { "Chevy" => "Chevrolet" }   # add your own make aliases
  config.use_cache = true                         # prefer a refreshed dataset over the bundled one
end

Staying current (optional)

The bundled snapshot works offline forever — but vehicle data changes (new makes, fixes), and you shouldn't have to ship a gem upgrade to every app just to get them. So vehicles can refresh from the published dataset into a local file cache; loads prefer the cache over the bundled copy. Data fixes reach your app without a gem bump.

rails g vehicles:install drops a VehiclesRefreshJob — schedule it (daily is plenty), e.g. with solid_queue:

# config/recurring.yml
vehicles_refresh:
  class: VehiclesRefreshJob
  schedule: every day at 3am

Or refresh manually:

Vehicles.refresh!     # pull latest -> cache; true/false, never raises
Vehicles.data_version # => the version now in effect (cached, or bundled)

It's safe by design: a failed/partial download never replaces good data, and the gem keeps serving the cache (or the bundled snapshot) no matter what. Want it fully offline/deterministic? config.use_cache = false.

The full Ruby API

# Lists (strings — drop straight into a form)
Vehicles.makes                          # => [String]
Vehicles.makes(kind: :car, region: :eu)
Vehicles.models("Audi")                 # => [String]
Vehicles.models("Audi", body_type: :suv)

# Option pairs (for Rails `select`)
Vehicles.make_options                   # => [[label, value]]
Vehicles.model_options("Audi")          # => [[label, value]]

# Whole make => [models] map (embed once for a client-side dependent picker)
Vehicles.catalog(kind: :car)            # => { "Audi" => ["A3", ...], ... }

# Objects
Vehicles.make("Audi")                   # => Vehicles::Make | nil
Vehicles.find("audi a3")                # => Vehicles::Model | nil  (one free-text string)
Vehicles.model("Audi", "A3")            # => Vehicles::Model | nil  (a stored make+model pair)
Vehicles.search("a3")                   # => [Vehicles::Model]

# Popularity & availability (open data, measured from official registers)
Vehicles.kinds                          # => [:bus, :car, :moped, :motorcycle, :truck, :van]
Vehicles.top_models(kind: :car, country: :nl, limit: 10)  # => [Vehicles::Model]

# Vehicles::Make
make.name      make.slug      make.aliases     make.kinds
make.models    make.model("a3")                make.to_h

# Vehicles::Model
model.make     model.name     model.full_name  model.slug    model.to_h
model.kind     model.body_type                 model.suv?    model.coupe?   # …predicates
model.global_decile   model.popular?           # 1 = top 10% worldwide; nil-safe
model.availability    model.available_in?(:nl) model.two_wheeler?
model.years    model.segment  model.image(year:, color:)     # ← hosted VehiclesDB API

# Colors (canonical palette)
Vehicles.colors                         # => [Vehicles::Color]
Vehicles.color("navy")                  # => Vehicles::Color | nil (forgiving)
Vehicles.color_options                  # => [[name, slug]]  (for select)
color.slug     color.name     color.hex

# Meta
Vehicles.data_version                   # => "2026.07.0"   (version in effect: cached or bundled)
Vehicles.region                         # => :global

# Refresh (optional — keep data current without a gem upgrade)
Vehicles.refresh!                       # pull latest published data -> cache; true/false, never raises
Vehicles.reload!                        # drop the in-memory dataset (reload from disk)

Where the data comes from

The bundled dataset is VehiclesDB — an open dataset reconciled from official vehicle registers of 14 countries on 4 continents (the Dutch RDW, UK DfT, Spanish DGT, Finnish Traficom, German KBA, US EPA, New Zealand's Motor Vehicle Register, Thailand's DLT, Ukraine's MVS, and more). A model ships only when two independent official sources corroborate it — or one shows a registration count no typo could produce — so you get real nameplates without the registry noise.

Every record is shaped like this:

{
  "name": "Volkswagen", "slug": "volkswagen", "kinds": ["car", "van"],
  "models": [
    { "name": "Golf", "slug": "golf", "kind": "car", "body_type": "hatchback",
      "global_decile": 2, "availability": ["ca", "es", "fi", "gb", "nl", "..."] }
  ]
}

kind is sourced, not guessed — straight from each register's official classification. body_type is curated on top (registers lump wagons, SUVs and crossovers together), mapped to a clean canonical vocabulary.
Nameplate-level, on purpose. "Golf" covers the GTI, the Variant, the R — that's what a dropdown wants. Two-wheelers keep displacement granularity ("Wave110i", "CBR600RR") because that's how riders and registers both speak. Per-trim and per-generation detail is a VehiclesDB API concern.
Popularity is measured, from real registration/fleet counts — never scraped rankings. Availability is evidence (a country appears because an official source shows the model there), not marketing history.
Source data: openly-licensed government sources only, every license pinned and verified at build time — full source list and attribution notices.
This dataset (data/vehicles.json): CC-BY 4.0. Attribution: "Vehicle data by VehiclesDB (CC-BY 4.0), built from official public registers."
The gem code: MIT.

The data is versioned (Vehicles.data_version). Each gem release bundles a known snapshot — the offline, deterministic floor. To get newer data, either upgrade the gem or enable refresh (which pulls published releases without a gem bump). Either way it's explicit and versioned — no silent mutations.

How it works

No magic, just good defaults:

Bundled, not fetched. data/vehicles.json is packaged in the gem and loaded into a frozen, memoized in-memory index on first access. First call builds the index; every call after is a hash lookup. No HTTP, no SQLite, no ActiveRecord on the read path.
Zero-config. No initializer required. No migration. Nothing to schedule.
Standalone first, SDK second. The hosted VehiclesDB layer is strictly optional and detected at runtime; the gem never hard-depends on it.
Rails-aware, not Rails-bound. Form helpers and validators register through a lightweight Railtie only when Rails is loaded.

Roadmap

Bundled today: 19k models across 6 kinds and 14 countries, with popularity + availability, plus the MCP server. On the way:

🌍 More countries (Switzerland next; the dataset grows monthly)
📅 Production years in the local data
🧬 Generations & variants layers (the schema already reserves them)
🖼️ Model images (via VehiclesDB)
🏷️ Segments (supercar, city car, hot hatch) and richer metadata
🔎 A mountable autocomplete endpoint so the dependent-dropdown recipe becomes one line

Want one of these sooner? Open an issue.

Testing

Run the test suite with bundle exec rake test. The gem is tested against multiple Rails versions with Appraisal: bundle exec appraisal rails-8.0 rake test.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/vehiclesdb/vehicles. Our code of conduct is: just be nice and make your mom proud of what you do and post online.

License

The gem is available as open source under the terms of the MIT License. The bundled dataset is licensed CC-BY 4.0 (see Where the data comes from).

🚗 vehicles – Car makes & models for your Rails app