cardog-ai
Corgi VIN Decoder
Fast, offline VIN decoding for Node.js, browsers, and Cloudflare Workers. Powered by the NHTSA VPIC database.
Installation
npm install @cardog/corgiQuick 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 --helpArchitecture
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 IdentifierWMI (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:
- Assigning each character a value (A=1, B=2, ..., N=5, P=7, ..., 0-9 = face value)
- Multiplying each position by a weight:
[8,7,6,5,4,3,2,10,0,9,8,7,6,5,4,3,2] - Summing all products and taking modulo 11
- 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 refreshExports
// 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.