# NRCan vehicle reference data

Contains information licensed under the Open Government Licence – Canada.

Provider: **Natural Resources Canada**. [Original dataset](https://open.canada.ca/data/dataset/98f1a129-f628-4ce4-b24d-6f16bf24dd64). [Open Government Licence – Canada](https://open.canada.ca/en/open-government-licence-canada).

Snapshot version: **nrcan-2026-10-31-partial**, downloaded 2026-10-31. The application and the derived snapshot are not endorsed by the Government of Canada. The licence permits reuse subject to its terms, including attribution. No government logos or endorsements are included.

## Coverage

This is a reference collection of **20,125 Canadian-market vehicle configurations from four source CSV files**, comprising 65 make names after surrounding whitespace is removed. It is not a worldwide vehicle registry and does not establish the specification of an individual VIN. The source model labels can include trims and drivetrain suffixes; distinct labels are not a count of canonical vehicle models.

| Source | Model years actually included | Records |
| --- | --- | ---: |
| Fuel consumption ratings, historical | 1995–2014 | 17,853 |
| Fuel consumption ratings, current | 2026 | 613 |
| Battery electric vehicles | 2012–2026 | 1,250 |
| Plug-in hybrid electric vehicles | 2012–2026 | 409 |

**Combustion data for 2015–2025 are missing from this snapshot.** The presence of electric and plug-in hybrid records in those years does not fill that gap. The historical 1995–2014 consumption ratings were approximately adjusted by the provider to the five-cycle methodology; they are not new five-cycle vehicle tests. The `ice` category identifies the combustion source tables and also includes their non-plug-in hybrids and alternative liquid/gaseous fuel configurations.

The application metadata reports the complete observed year list for each source. Source publication dates are retained where available: 2026 fuel ratings, 2026-10-06; the BEV and PHEV files, 2026-09-29. No historical-file update date is inferred. Snapshot freshness does not imply new test results for older model years.

## Relationship to VIN results

This collection contains no VIN-to-configuration mapping. It must appear as **reference specifications for a model/configuration**, separate from decoded VIN fields. Do not copy its engine, fuel, transmission, consumption, emissions, or range into a decoded VIN result.

Exact normalized make, complete model label, and numeric model year can narrow the candidate set. They cannot confirm an individual vehicle's equipment, market, trim, engine, transmission, parts compatibility, or recall applicability. Do not remove suffixes such as AWD, Hybrid, Coupe, or engine designations to imply a stronger match. If a VIN decoder does not supply an exact compatible label, let the visitor search or select a reference configuration independently. Even one matching reference row is not VIN verification.

## Fields and units

Source text labels are preserved with surrounding whitespace removed. Missing numbers, including empty cells, `ND`, `N/A`, and dash markers, are `null`; zero is preserved. Unsupported numerical notation causes import failure instead of silently guessing.

| API field | Interpretation |
| --- | --- |
| `engineL`, `cylinders` | Values from the combustion engine columns. Absent for BEVs, so `null`. |
| `transmission` | Original NRCan transmission code; no automatic transmission inference from a name. |
| `fuel` | Original fuel codes. For a PHEV, both source operating-mode fuels are included without duplicate codes; the original asterisk is retained. |
| `combinedL100km` | Dedicated source `Combined (L/100 km)` liquid/gaseous-fuel column. Always `null` for BEVs. For PHEVs, this is the source's gasoline operating mode, not its mode-1 blended result. |
| `combinedEquivalentL100km` | Energy-equivalent **Le/100 km**. This is not gasoline L/100 km. |
| `combinedElectricKWh100km` | Combined electric consumption component in **kWh/100 km**. For a PHEV, liquid fuel may be consumed at the same time. |
| `chargeDepletingL100km` | PHEV mode-1 liquid-fuel component explicitly printed in the bracketed formula. For example, `2.4 ([20.0 kWh + 0.2 L]/100 km)` gives 0.2 L/100 km. If no liquid component is printed, this field remains `null`, not an inferred zero. |
| `co2GKm` | Source CO2 emissions in g/km. Source zero is preserved. This is not a life-cycle or electricity-generation emissions estimate. |
| `electricRangeKm` | BEV `Range (km)`, or PHEV `Range 1 (km)` only when source `Fuel type 1` is exactly `B`. |
| `chargeDepletingRangeKm` | PHEV `Range 1 (km)` in its initial operating mode. That mode may blend electricity and gasoline; do not label this universally as electric-only range. |
| `powertrain` | `ice`, `bev`, or `phev`, assigned from the corresponding source table. |
| `sourceId` | Stable source identifier resolving to metadata and the pinned original CSV. |

Fuel codes include `X` regular gasoline, `Z` premium gasoline, `D` diesel, `E` E85, `N` natural gas and `B` electricity. Source asterisks and compound fuel codes are retained; they should not be discarded to infer guaranteed electric-only operation. [NRCan table guidance](https://natural-resources.canada.ca/energy-efficiency/transportation-energy-efficiency/personal-vehicles/understanding-tables).

The importer supports both explicit PHEV expressions, such as `2.5 (22.3 kWh/100 km)`, and mixed expressions, such as `2.4 ([20.0 kWh + 0.2 L]/100 km)`. These become separately named numeric fields. No unit conversion is estimated. City/highway values, motor power, secondary ranges, recharge times and ratings remain accessible in the original CSVs but are not included in the compact API record.

## API and search

`GET /api/specs?meta=1` returns `{ok:true,meta,makes}`. Source records, dates, licence, hashes and exact observed years are part of `meta`.

`GET /api/specs?q=toyota%20prius&year=2026&offset=0&limit=12` returns `{ok:true,total,offset,limit,items}`. Optional `make` and `model` filters are exact after case, accent and whitespace normalization. Every normalized `q` token must appear in make plus model. Year is an exact numeric model year. No fuzzy matching, aliases, translation or VIN inference is applied. Empty text filters do not constrain the results. Stable ordering is descending model year, make, model, then record ID.

Default limit is 12; valid limits are 1–60. Offset is a nonnegative safe integer. Invalid, duplicate or unknown parameters return HTTP 400. Metadata mode accepts only `meta=1`. The API reads a pinned local snapshot and performs no external fetches.

## Reproducing the snapshot

The original four CSV files are redistributed byte-for-byte in this directory. `source-manifest.json` records their URLs, SHA-256 hashes, byte sizes, columns, row counts and known publication dates. It also lists modifications and the two files that were not imported.

From the project root:

```sh
python scripts/import-vehicle-specs.py
node scripts/test-specs.mjs
```

The importer uses only local files, validates their pinned hashes and schemas, preserves all source records, and generates deterministic compact JSON in `data/vehicle-specs.json`. It can also use `--source-dir PATH` and `--output PATH`. Updating the snapshot requires an explicit new source manifest; it does not silently download or replace upstream files. All field transformations are documented in the manifest, this note, and the importer. Record IDs are derived from source ID and source row content with surrounding field whitespace removed, not from a VIN.