Corgi VIN Decoder

Fast, offline VIN decoding for Node.js, browsers, and Cloudflare Workers. Powered by the NHTSA VPIC database.

Installation

npm install @cardog/corgi

Quick Start

import { createDecoder } from "@cardog/corgi";

const decoder = await createDecoder();
const result = await decoder.decode("KM8K2CAB4PU001140");

console.log(result.components.vehicle);
// { make: 'Hyundai', model: 'Kona', year: 2023, ... }

await decoder.close();

Platform Support

Node.js

import { createDecoder } from "@cardog/corgi";

const decoder = await createDecoder();
const result = await decoder.decode("1HGCM82633A123456");

// Custom database path
const decoder = await createDecoder({
  databasePath: "/path/to/vpic.lite.db",
});

Browser

import { createDecoder } from "@cardog/corgi/browser";

const decoder = await createDecoder({
  databasePath: "https://corgi.cardog.io/vpic.lite.db.gz",
  runtime: "browser",
});

Cloudflare Workers (D1)

import { createDecoder, initD1Adapter } from "@cardog/corgi";

initD1Adapter(env.D1_DATABASE);

const decoder = await createDecoder({
  databasePath: "D1",
  runtime: "cloudflare",
});

Configuration

const decoder = await createDecoder({
  databasePath: "./custom/path.db",
  forceFresh: true,
  defaultOptions: {
    includePatternDetails: true,
    includeRawData: false,
    confidenceThreshold: 0.8,
    includeDiagnostics: true,
  },
});

// Per-decode options
const result = await decoder.decode("VIN12345678901234", {
  modelYear: 2024,
  includePatternDetails: true,
});

Response Structure

interface DecodeResult {
  vin: string;
  valid: boolean;

  components: {
    vehicle?: {
      make: string;
      model: string;
      year: number;
      series?: string;
      bodyStyle?: string;
      driveType?: string;
      fuelType?: string;
      doors?: string;
    };
    wmi?: {
      manufacturer: string;
      make: string;
      country: string;
      region: string;
    };
    plant?: {
      country: string;
      city?: string;
      code: string;
    };
    engine?: {
      model?: string;
      cylinders?: string;
      displacement?: string;
      fuel?: string;
    };
    modelYear?: {
      year: number;
      source: string;
      confidence: number;
    };
    checkDigit?: {
      isValid: boolean;
      expected?: string;
      actual: string;
    };
  };

  errors: DecodeError[];
  metadata?: DiagnosticInfo;
  patterns?: PatternMatch[];
}

Error Handling

import { ErrorCode } from "@cardog/corgi";

const result = await decoder.decode("INVALID_VIN");

if (!result.valid) {
  result.errors.forEach((error) => {
    switch (error.code) {
      case ErrorCode.INVALID_CHECK_DIGIT:
      case ErrorCode.INVALID_LENGTH:
      case ErrorCode.WMI_NOT_FOUND:
        console.log(error.message);
    }
  });
}

CLI

npx @cardog/corgi decode 1HGCM82633A123456
npx @cardog/corgi decode 1HGCM82633A123456 --patterns --format json
npx @cardog/corgi --help

Architecture

VIN Structure

A Vehicle Identification Number (VIN) is a 17-character identifier assigned to every vehicle manufactured for road use. The structure is defined by ISO 3779 and follows this format:

Position:  1-3    4-8      9       10      11      12-17
           WMI    VDS      Check   Year    Plant   VIS
           │      │        │       │       │       │
           │      │        │       │       │       └─ Sequential production number
           │      │        │       │       └───────── Assembly plant code
           │      │        │       └─────────────── Model year (A-Y, 1-9, excluding I,O,Q,U,Z,0)
           │      │        └─────────────────────── Check digit (0-9, X)
           │      └──────────────────────────────── Vehicle attributes (model, body, engine, etc.)
           └─────────────────────────────────────── World Manufacturer Identifier

WMI (Positions 1-3): Identifies the manufacturer. First character indicates country/region, second indicates manufacturer, third indicates vehicle type or manufacturing division.

VDS (Positions 4-8): Vehicle Descriptor Section. Manufacturer-defined attributes including model, body style, engine type, and restraint system.

Check Digit (Position 9): Validates VIN integrity using a weighted algorithm. Required for all vehicles sold in North America.

Model Year (Position 10): Encodes the model year. Uses letters A-Y (excluding I, O, Q, U, Z) and digits 1-9 in a 30-year cycle.

Plant Code (Position 11): Identifies the assembly plant. Manufacturer-specific encoding.

VIS (Positions 12-17): Vehicle Identifier Section. Sequential production number unique within the model year and plant.

Check Digit Algorithm

The check digit (position 9) is calculated by:

1. Assigning each character a value (A=1, B=2, ..., N=5, P=7, ..., 0-9 = face value)
2. Multiplying each position by a weight: [8,7,6,5,4,3,2,10,0,9,8,7,6,5,4,3,2]
3. Summing all products and taking modulo 11
4. Result 10 = 'X', otherwise the digit itself

Model Year Decoding

Per 49 CFR 565.15, model year codes cycle every 30 years:

| Code | Years | |------|-------| | A | 1980, 2010 | | B | 1981, 2011 | | ... | ... | | X | 1999, 2029 | | Y | 2000, 2030 | | 1 | 2001, 2031 | | ... | ... | | 9 | 2009, 2039 |

Characters I, O, Q are excluded from all VIN positions. U, Z, and 0 are additionally excluded from position 10.

Database

VPIC Lite

Corgi uses an optimized subset of the NHTSA vPIC (Vehicle Product Information Catalog) database. The database is compressed and bundled with the package for offline operation.

Specifications:

• Source: NHTSA VPIC
• Format: SQLite (optimized)
• Compressed: ~20MB (gzip)
• Uncompressed: ~40MB
• Updates: Monthly via automated pipeline

Hosted Database

Cardog maintains a public CDN with the latest VPIC database builds:

Base URL: https://corgi.cardog.io

| File | Description | |------|-------------| | vpic.lite.db.gz | Database (gzip) | | vpic.lite.db.bz2 | Database (bzip2) | | vpic.lite.db.xz | Database (xz) | | vpic.lite.db.zst | Database (zstd) | | vpic.lite.json | Metadata (version, checksums, record counts) | | vpic.lite.sha256 | SHA256 checksums |

Dated archives are also available: vpic_lite_YYYYMMDD.db.gz

Local Cache

• Node.js: ~/.corgi-cache/vpic.lite.db
• Browser: Loaded from provided URL
• Cloudflare: Managed by D1

import { getDatabasePath } from "@cardog/corgi";

const dbPath = await getDatabasePath();
const decoder = await createDecoder({ forceFresh: true }); // Force refresh

Exports

// Core
import { createDecoder, quickDecode, getDatabasePath } from "@cardog/corgi";

// Types
import type { DecodeResult, DecodeOptions, DecoderConfig } from "@cardog/corgi";

// Enums
import { ErrorCode, ErrorCategory, BodyStyle } from "@cardog/corgi";

// Adapters
import { initD1Adapter } from "@cardog/corgi/d1-adapter";
import { createDecoder } from "@cardog/corgi/browser";

License

ISC License - see LICENSE for details.