vehicles 0.4.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99ccb43a3ef0091206a4e6a7445c48333886f0a26cfd9a1764397e0c5ec46516
-  data.tar.gz: b2a878137e3861323aaf59f12c0f5f44052b5ed064bc2f519b7247aaca916027
+  metadata.gz: d31bdc07c2c1c97fe6e2f3f6de9bd94545f75cd69629a0ecc49171d369d7fee6
+  data.tar.gz: afc63731709c038bd56171d50a30ddb8a06253f5fc51e86d2b3f7d36c0540c05
 SHA512:
-  metadata.gz: c7c2b0995cb72a450f91ab1c7d37e8c1d0ebb439358a09572e467d4786dd0edca211c904d9194ef42f3e6563ba1719b32041c645d0d25bd2f85c663607e58840
-  data.tar.gz: 0a3c8914e5d5fc681ef7b83b2062746b382f0281c0ae75475120acb3227d8d2d7349e1c2f0c2769f62e6f8f6130733430f4d2b25db3ce27780989bf9326f4bba
+  metadata.gz: 2e0b37318a2131f1c35ecaaca88e72d4d967d9ad134c8777a6f0c2dda0d4105792c7eb2bd749ba0891a94dbac2761b60c947004376b478a3bb66f78e6f01bf2b
+  data.tar.gz: 6a215001415080252d699ee3a202043c9685f6286a8763896db3371a81f9458ab01afcb58ca253e2f8a4cac652782564050246fc493911854c4c3756154a089d

data/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-08-01
+
+### Added
+
+- `Model#former_ids` — the full canonical ids a record absorbed through the
+  dataset's append-only migration contract (e.g. `car/alfa-romeo/159sw`).
+  The field was already in the bundled snapshot; the reader now surfaces it,
+  so integrators can migrate stored ids without re-parsing the raw JSON.
+  Also included in `Model#to_h`.
+
+## [0.6.0] - 2026-07-27
+
+License plates become a first-class citizen: the PRD-PLATES registration-mark
+dataset ships in the gem, bundled and offline like everything else.
+
+### Added
+- `Vehicles.plate(input, jurisdiction:)` — two-tier plate validation:
+  exact as-issued, then separator-forgiving ("1234XYZ" == "1234 XYZ" ==
+  "1234-xyz") with `Match#suggestion` returning the as-issued formatting.
+  Leniency forgives punctuation, never the alphabet — strict regexes encode
+  what each authority really issues. `Match#strict?` separates
+  authority-alphabet hits from recall-only catch-alls (export plates etc.).
+- `Vehicles.plates` / `Vehicles.plates(:nl)` — the full series data:
+  73 series across NL/ES/DE/US-FL (gate L0, NL corpus-proven), each with
+  pattern, period, class, categories, sourced design facts and citations.
+- Bundled data under `data/plates/` (CC-BY, pinned upstream commit in
+  `data/plates/PROVENANCE.md`).
+
+The hosted images API is **live** — this release points the wired-up provider
+seam at the real thing.
+
+### Added
+- `Model#image(color:, size:)` returns a rendered variant URL from the live
+  VehiclesDB images API (`:sm` 320×180, `:md` 640×360, `:lg` 1280×720, webp).
+  Mint a key at <https://vehiclesdb.com/settings/api-keys> and set
+  `config.api_key`; without a key it stays nil, as always.
+- `Model#images(color:)` returns the full payload: every variant with
+  dimensions, the rendered palette for the model, served-vs-requested color
+  (un-rendered colors fall back honestly instead of 404ing), provenance.
+
+### Changed
+- `config.api_base_url` default is now `https://vehiclesdb.com` (the live API
+  origin; endpoint paths carry `/v1`). It must be an ORIGIN — no path suffix.
+- `Model#image` accepts `year:` but does not send it: `year`/`trim` are
+  reserved filters server-side (the API 422s on them by contract) until
+  year-accurate renders ship.
+
 ## [0.4.1] - 2026-07-26
 
 Data-only refresh to VehiclesDB dataset **2026.07.4** — the July correction

data/README.md

@@ -432,6 +432,25 @@ Vehicles.makes(region: :eu)   # fine — a global snapshot covers the EU
 Vehicles.region               # => :global
 ```
 
+## License plates
+
+The gem bundles the VehiclesDB **registration-mark dataset** (PRD-PLATES): every plate series per jurisdiction, researched to the issuing authority's own documents — formats, eras, alphabets, designs. Ask it whether a typed registration is real:
+
+```ruby
+Vehicles.plate("12-GB-BD", jurisdiction: :nl).valid?    # => true — exact, as issued
+Vehicles.plate("12gbbd", jurisdiction: :nl).suggestion  # => "12-GB-BD"  (did you mean)
+Vehicles.plate("12-AB-CD", jurisdiction: :nl).strict?   # => false — vowels aren't issued
+```
+
+Matching is **two-tier**: exact as-issued first, then a separator-forgiving tier — `"1234XYZ"`, `"1234 xyz"` and `"1234-XYZ"` all resolve to the same serial, with `suggestion` giving the formatting the plate actually wears. Leniency forgives punctuation, **never the alphabet**: the strict regexes encode what the authority really issues (the Dutch vowel purge, the Spanish consonant-triplet rule…). `Match#strict?` separates authority-alphabet hits from recall-only catch-alls (export plates accept any current shape, by law).
+
+```ruby
+Vehicles.plates              # => every jurisdiction
+Vehicles.plates(:es).series  # => 18 series: formats, periods, sourced designs
+```
+
+Pilot coverage (gate L0): 🇳🇱 🇪🇸 🇩🇪 + US-Florida, 73 series, corpus-proven in NL. Same posture as everything else here: bundled, offline, forgiving in, honest out.
+
 ## 🔓 More with VehiclesDB
 
 `vehicles` is the free, open-source SDK for [**VehiclesDB**](https://vehiclesdb.com) — 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:
@@ -442,11 +461,20 @@ Vehicles.configure do |config|
 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)
+
+# Rendered vehicle imagery — LIVE today. Mint a key at
+# https://vehiclesdb.com/settings/api-keys
+car.image                        # => "https://vehiclesdb.com/…/md.webp"  (640×360)
+car.image(size: :lg)             # :sm 320×180 · :md 640×360 · :lg 1280×720
+car.image(color: "red")          # color-accurate; un-rendered colors fall back honestly
+car.images(color: "red")         # the full payload: every variant + dimensions,
+                                 #    rendered palette, served-vs-requested color
+# color slugs are the gem's own canon — Vehicles.colors — so a stored
+# dropdown value maps 1:1 to the rendered imagery.
+
+# Enrichment — the wired-up seam; ships next. nil until then, same objects.
+car.years                        # => 1974..2024            production years
+car.segment                      # => :hatchback / :hot_hatch   editorial segment
 ```
 
 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:

data/data/plates/PROVENANCE.md

@@ -0,0 +1,9 @@
+# Bundled plates dataset (PRD-PLATES L0)
+
+Copy of `plates/` from the public data repo, refreshed on gem releases:
+
+- **Source**: https://github.com/vehiclesdb/vehiclesdb `plates/`
+- **Commit**: `69c8dab39424cf50ff8d1a526216551c8a9cb12f`
+- **License**: CC-BY 4.0 (see the data repo's LICENSE + ATTRIBUTION.md)
+
+Refresh: copy the source tree over this directory and update the commit line.

data/data/plates/_decode/es-provinces.yml

@@ -0,0 +1,116 @@
+# plates/_decode/es-provinces.yml — Spanish province contraseñas.
+#
+# THE SOURCE FINDING: this table is PRIMARY, not Wikipedia. The EU research
+# dossier recorded that "Wikipedia supplies the full code table" for the
+# pre-2000 Spanish provincial system. It is in fact enacted law: Reglamento
+# General de Vehículos (RD 2822/1998) ANEXO XVIII, section
+# "II. Contraseñas de las placas — A. Siglas de provincias", which lists all
+# 52 codes. Every row below is that table, verbatim, in its own order
+# (alphabetical by province name as the BOE prints it).
+#
+# Referenced by: es-provincial (plates/es.yml) via region_encoding.
+#
+# PERIOD DISCIPLINE (PRD-PLATES §2.4 — "province codes changed over time"):
+# these codes are the set in force in the CONSOLIDATED Anexo XVIII, and they
+# use the CURRENT official province names (Illes Balears, Girona, Lleida,
+# Ourense, A Coruña). Historic contraseñas that predate the RGV and appear on
+# older plates — PM for Baleares, GE for Gerona, OR for Orense, and the
+# pre-1982 forms — are NOT in this primary and are NOT invented here; they are
+# a recorded gap for gate L1/L4. A decode of a physical plate older than the
+# RGV must therefore be treated as unresolved rather than mapped through this
+# table.
+jurisdiction: es
+topic: provinces
+authority:
+  name: Reglamento General de Vehículos (RD 2822/1998), Anexo XVIII II.A
+  url: "https://www.boe.es/buscar/act.php?id=BOE-A-1999-1826"
+sources:
+  - "https://www.boe.es/buscar/pdf/1999/BOE-A-1999-1826-consolidado.pdf  # Anexo XVIII, II. Contraseñas de las placas, A. Siglas de provincias — all 52 rows"
+  - "https://www.boe.es/buscar/doc.php?id=BOE-A-1999-1826  # original enacted text (in force 26-07-1999), same section"
+period: { start: 1999 }
+period_evidence: instrument-in-force
+period_note: >-
+  The contraseñas long predate RD 2822/1998; 1999 is the date of the instrument
+  that ENACTS the list read here, not the date the codes came into use. Codes
+  remain decodable indefinitely because provincial plates stay valid: RD
+  2822/1998 disposición transitoria preserves them, and the Orden of 15-09-2000
+  only stopped ISSUING them (in force 17-09-2000).
+
+# Ambiguity notes a parse API must carry:
+#   * CC decodes to CÁCERES here AND is the consular series prefix
+#     (Anexo XVIII I.B.a).3). Disambiguate on group structure, not prefix:
+#     provincial = 4 digits + 1-2 letters; consular = two digit groups.
+#   * C (A Coruña) vs CA (Cádiz) vs CC (Cáceres) vs CE (Ceuta) vs CO (Córdoba)
+#     vs CR (Ciudad Real) vs CS (Castellón) vs CU (Cuenca): the code is
+#     MAXIMAL-MUNCH — always take the longest matching code before the digits.
+#   * S (Cantabria) vs SA / SE / SG / SO / SS: same rule.
+#   * L (Lleida) vs LE / LO / LU: same rule.
+#   * O (Asturias) vs OU (Ourense): same rule.
+#   * Z (Zaragoza) vs ZA (Zamora): same rule.
+#   * Ceuta (CE) and Melilla (ML) are autonomous cities, not provinces; the
+#     BOE table lists them under the same heading.
+maximal_munch: true
+
+codes:
+  - { code: VI,  name: "Álava" }
+  - { code: AB,  name: "Albacete" }
+  - { code: A,   name: "Alicante" }
+  - { code: AL,  name: "Almería" }
+  - { code: O,   name: "Asturias" }
+  - { code: AV,  name: "Ávila" }
+  - { code: BA,  name: "Badajoz" }
+  - { code: B,   name: "Barcelona" }
+  - { code: BU,  name: "Burgos" }
+  - { code: CC,  name: "Cáceres" }
+  - { code: CA,  name: "Cádiz" }
+  - { code: S,   name: "Cantabria" }
+  - { code: CS,  name: "Castellón" }
+  - { code: CR,  name: "Ciudad Real" }
+  - { code: CO,  name: "Córdoba" }
+  - { code: C,   name: "A Coruña" }
+  - { code: CU,  name: "Cuenca" }
+  - { code: GI,  name: "Girona" }
+  - { code: GR,  name: "Granada" }
+  - { code: GU,  name: "Guadalajara" }
+  - { code: SS,  name: "Guipúzcoa" }
+  - { code: H,   name: "Huelva" }
+  - { code: HU,  name: "Huesca" }
+  - { code: IB,  name: "Illes Balears" }
+  - { code: J,   name: "Jaén" }
+  - { code: LE,  name: "León" }
+  - { code: L,   name: "Lleida" }
+  - { code: LU,  name: "Lugo" }
+  - { code: M,   name: "Madrid" }
+  - { code: MA,  name: "Málaga" }
+  - { code: MU,  name: "Murcia" }
+  - { code: NA,  name: "Navarra" }
+  - { code: OU,  name: "Ourense" }
+  - { code: P,   name: "Palencia" }
+  - { code: GC,  name: "Las Palmas" }
+  - { code: PO,  name: "Pontevedra" }
+  - { code: LO,  name: "La Rioja" }
+  - { code: SA,  name: "Salamanca" }
+  - { code: TF,  name: "Santa Cruz de Tenerife" }
+  - { code: SG,  name: "Segovia" }
+  - { code: SE,  name: "Sevilla" }
+  - { code: SO,  name: "Soria" }
+  - { code: T,   name: "Tarragona" }
+  - { code: TE,  name: "Teruel" }
+  - { code: TO,  name: "Toledo" }
+  - { code: V,   name: "Valencia" }
+  - { code: VA,  name: "Valladolid" }
+  - { code: BI,  name: "Vizcaya" }
+  - { code: ZA,  name: "Zamora" }
+  - { code: Z,   name: "Zaragoza" }
+  - { code: CE,  name: "Ceuta",   kind: autonomous-city }
+  - { code: ML,  name: "Melilla", kind: autonomous-city }
+
+# State and NATO contraseñas from the SAME Anexo XVIII section (II.B) are
+# modelled as series in plates/es.yml (es-military-1999, es-nato-fae-1999,
+# es-government-1999, es-police-1999) rather than as decode rows, because they
+# are issuance series in their own right and not a geographic decode.
+state_codes_see_also:
+  - "plates/es.yml#es-military-1999   # ET Ejército de Tierra, FN Armada, EA Ejército del Aire"
+  - "plates/es.yml#es-government-1999 # MF Fomento, MMA Medio Ambiente, PME Parque Móvil del Estado"
+  - "plates/es.yml#es-police-1999     # CNP Cuerpo Nacional de Policía, PGC Guardia Civil"
+  - "plates/es.yml#es-nato-fae-1999   # FAE NATO international military headquarters in Spain"

data/data/plates/_meta/classes.yml

@@ -0,0 +1,25 @@
+# The controlled vocabulary of plate classes (PRD-PLATES §2.3). A class is a
+# LEGAL/ADMINISTRATIVE issuance category, not a design variant. A
+# jurisdiction's variant becomes its OWN SERIES iff format OR design OR
+# period differs from the standard series; a color-only variant of the same
+# format+period is a sub-entry on the standard series. Grow this file by PR
+# with a definition — never ad hoc in data files.
+standard:       the default series issued to private road vehicles
+motorcycle:     reduced-size series for motorcycles where format/design differs
+moped:          insurance/registration plates for mopeds (NL/DE small plates)
+trailer:        trailers and semi-trailers where separately serialized
+diplomatic:     diplomatic corps (embassy) issuance, usually its own decode
+consular:       consular corps where distinct from diplomatic
+temporary:      short-validity plates (transit, awaiting registration)
+export:         plates for vehicles leaving the jurisdiction permanently
+dealer:         trade/garage plates bound to a business, not a vehicle
+historic:       vintage/oldtimer regimes (German H, ES historico)
+taxi:           for-hire vehicles where separately serialized or colored
+government:     civil government fleets with distinct series
+military:       armed-forces registration systems
+police:         police fleets where distinct from government
+electric:       EV-distinct plates or suffixes (German E, CN green plates)
+seasonal:       validity-window plates (German Saisonkennzeichen)
+agricultural:   farm vehicles/equipment where separately serialized
+personalized:   owner-chosen serials inside an official frame
+specialty:      optional-design programs on standard serials (US state programs)