NHTSA VIN Decoder

World-class VIN decoder with comprehensive offline database (2,015+ WMI codes) and NHTSA vPIC API integration

Sister Projects

Part of the NHTSA automotive diagnostic toolkit:

nhtsa-vin-decoder - This project (VIN decoder)
nhtsa-recall-lookup - Look up safety recalls using decoded vehicle info
dtc-database - Comprehensive OBD-II diagnostic trouble code database

Workflow: Decode VIN → Get vehicle info → Look up recalls → Decode diagnostic codes

⚡ Quick Start

Java - Offline Mode (No Internet Required)

import io.github.vindecoder.offline.OfflineVINDecoder;
import io.github.vindecoder.nhtsa.VehicleData;

OfflineVINDecoder decoder = new OfflineVINDecoder();
VehicleData vehicle = decoder.decode("1HGCM82633A004352");

System.out.println(vehicle.getModelYear() + " " +
                   vehicle.getMake() + " " +
                   vehicle.getModel());
// Output: 2003 Honda Accord

Android - With Async Callbacks

import io.github.vindecoder.android.VINDecoderAndroid;
import io.github.vindecoder.nhtsa.VehicleData;

VINDecoderAndroid decoder = new VINDecoderAndroid(context);
decoder.decodeAsync("1HGCM82633A004352", new VINDecoderAndroid.DecodeCallback() {
    @Override
    public void onSuccess(VehicleData vehicle) {
        // Called on main thread
        Log.d("VIN", vehicle.getModelYear() + " " + vehicle.getMake());
        // Output: 2003 Honda
    }

    @Override
    public void onError(String error) {
        Log.e("VIN", "Decode failed: " + error);
    }
});

Python - With NHTSA API

from python.nhtsa_vin_decoder import NHTSAVinDecoder

decoder = NHTSAVinDecoder()
vehicle = decoder.decode("1HGCM82633A004352")

print(f"{vehicle.year} {vehicle.make} {vehicle.model}")
# Output: 2003 Honda Accord

Python - Offline Mode

from python.wmi_database import WMIDatabase

manufacturer = WMIDatabase.get_manufacturer("1HGCM82633A004352")
year = WMIDatabase.get_year("1HGCM82633A004352")

print(f"{year} {manufacturer}")
# Output: 2003 Honda

TypeScript/JavaScript - Auto-Fallback (API → Offline)

import { VINDecoder } from '@wal33d/nhtsa-vin-decoder';

// Default: Tries NHTSA API first, falls back to offline WMI database
const decoder = new VINDecoder();
const vehicle = await decoder.decode('1HGCM82633A004352');
console.log(`${vehicle.make} ${vehicle.model} ${vehicle.bodyClass}`);
// Output: Honda Accord Sedan (from API)
// Falls back to offline if API unavailable

// Force offline-only mode
const offlineDecoder = new VINDecoder({ online: false });
const offlineData = await offlineDecoder.decode('1HGCM82633A004352');
console.log(`${offlineData.modelYear} ${offlineData.manufacturer}`);
// Output: 2003 Honda (from WMI database)

🎯 Overview

Advanced VIN decoder featuring both enhanced offline decoding capabilities and official NHTSA vPIC API integration. Provides complete vehicle specifications through manufacturer-specific decoders and a comprehensive WMI database with 2,015+ manufacturer codes.

✨ Features

Enhanced Offline Decoder - Full VIN decoding without internet
2,015+ Manufacturer Codes - Comprehensive WMI database (6x industry standard)
Manufacturer-Specific Decoders - Detailed model/trim/engine extraction
VIN Validation - Check digit verification per ISO 3779
Year Decoding - Accurate model year extraction (1980-2039)
Official NHTSA API - Falls back to government database when online
Automatic Fallback - Seamlessly switches between offline/online
FREE - No API key required
Caching - Built-in LRU cache to reduce API calls
Multi-platform - Java, Android, Python, and TypeScript/JavaScript implementations

📁 Directory Structure

nhtsa-vin-decoder/
├── java/io/github/vindecoder/
│   ├── offline/                    # Offline decoder implementation
│   │   ├── OfflineVINDecoder.java  # Main offline decoder
│   │   ├── VINValidator.java       # VIN validation & structure
│   │   ├── WMIDatabase.java        # 948+ manufacturer codes
│   │   └── MercedesBenzDecoder.java # Example manufacturer decoder
│   └── nhtsa/                      # NHTSA API integration
│       ├── VINDecoderService.java
│       ├── VehicleData.java
│       └── NHTSAApiService.java
├── android/                        # Android wrapper library
│   └── nhtsa-vin-decoder-android/
│       └── src/main/java/io/github/vindecoder/android/
│           └── VINDecoderAndroid.java  # Android-friendly async API
├── python/                         # Python implementation
│   ├── nhtsa_vin_decoder.py       # Main decoder with API
│   └── wmi_database.py            # Offline WMI database
├── data/                          # Reference data (not used at runtime)
│   ├── *.csv                      # Source WMI data from WALL-E/vin-decoder
│   ├── process_wmi.py             # Script to regenerate database
│   └── wmi_database_generated.java # Generated code
└── docs/                          # Documentation
    ├── ADDING_DECODERS.md        # Guide for adding manufacturers
    ├── VIN_DECODER_RESOURCES.md  # External data sources
    ├── API.md                    # Complete API reference
    ├── INSTALLATION.md           # Setup guide
    ├── USAGE.md                  # Examples and best practices
    └── WMI_DATABASE.md          # Offline database details

🚀 What You Get

Offline Decoding (No Internet Required)

{
  "vin": "4JGDA5HB7JB158144",
  "make": "Mercedes-Benz",
  "manufacturer": "Mercedes-Benz (Daimler AG)",
  "model": "GLE-Class",
  "year": "2018",
  "trim": "GLE 350 4MATIC",
  "vehicle_type": "Sport Utility Vehicle (SUV)",
  "body_class": "Sport Utility Vehicle (SUV)",
  "doors": "4",
  "drive_type": "4MATIC",
  "engine_model": "3.5L V6",
  "engine_cylinders": "6",
  "engine_displacement_l": "3.5",
  "fuel_type": "Gasoline",
  "transmission_style": "Automatic",
  "transmission_speeds": "9",
  "plant_city": "Tuscaloosa",
  "plant_state": "Alabama",
  "plant_country": "United States",
  "gvwr": "6062",
  "curb_weight": "4630"
}

Online Mode (Full NHTSA Data)

All of the above PLUS safety ratings, NCAP data, and more.

Looking for Recall Data?

For vehicle recall information, check out our sister project: NHTSA Recall Lookup

💻 Quick Start

Java - Offline Mode (No Internet)

import io.github.vindecoder.offline.OfflineVINDecoder;
import io.github.vindecoder.nhtsa.VehicleData;

OfflineVINDecoder decoder = new OfflineVINDecoder();
VehicleData vehicle = decoder.decode("4JGDA5HB7JB158144");

System.out.println("Vehicle: " + vehicle.getModelYear() + " " +
                   vehicle.getMake() + " " + vehicle.getModel());
// Output: Vehicle: 2018 Mercedes-Benz GLE-Class

System.out.println("Trim: " + vehicle.getTrim());
// Output: Trim: GLE 350 4MATIC

System.out.println("Engine: " + vehicle.getEngineModel());
// Output: Engine: 3.5L V6

Java - With NHTSA API

VINDecoderService decoder = VINDecoderService.getInstance();

decoder.decodeVIN("4JGDA5HB7JB158144", new VINDecoderCallback() {
    @Override
    public void onSuccess(VehicleData vehicle) {
        // Full NHTSA data returned
        System.out.println("Vehicle: " + vehicle.getDisplayName());
    }

    @Override
    public void onError(String error) {
        // Automatically falls back to offline decoder
        VehicleData vehicle = new OfflineVINDecoder().decode(vin);
    }
});

Android - Complete Example

import io.github.vindecoder.android.VINDecoderAndroid;
import io.github.vindecoder.nhtsa.VehicleData;

public class MainActivity extends AppCompatActivity {
    private VINDecoderAndroid decoder;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        decoder = new VINDecoderAndroid(this);

        // Async decode with main thread callbacks
        decoder.decodeAsync("4JGDA5HB7JB158144", new VINDecoderAndroid.DecodeCallback() {
            @Override
            public void onSuccess(VehicleData vehicle) {
                // Safe to update UI - callback runs on main thread
                textView.setText(vehicle.getModelYear() + " " +
                               vehicle.getMake() + " " +
                               vehicle.getModel());
            }

            @Override
            public void onError(String error) {
                Toast.makeText(MainActivity.this, error, Toast.LENGTH_SHORT).show();
            }
        });

        // Or use synchronous methods on background thread
        new Thread(() -> {
            VehicleData vehicle = decoder.decode("4JGDA5HB7JB158144");
            runOnUiThread(() -> {
                // Update UI
            });
        }).start();
    }
}

🧪 Testing

Java (Year Decoding Test)

Using Gradle (recommended):

./gradlew test

This runs JUnit tests validating VIN model year decoding across the 30-year cycle, including 2031–2039 (digit codes with position 7 letter heuristic).

Python (Year Decoding Test)

Run tests:

python3 tests/test_year.py

This validates the Python WMI fallback year-decoding heuristic matches the Java logic.

Python

from python.nhtsa_vin_decoder import NHTSAVinDecoder

decoder = NHTSAVinDecoder()
vehicle = decoder.decode("4JGDA5HB7JB158144")

print(f"Vehicle: {vehicle.year} {vehicle.make} {vehicle.model}")
# Output: Vehicle: 2018 Mercedes-Benz GLE-Class

📊 Offline Decoder Coverage

Global Manufacturer Support (2,015+ WMI Codes)

North America (Complete)

United States: Ford, GM, Tesla, Rivian, Lucid
Canada: All manufacturers
Mexico: All manufacturers

Europe (Comprehensive)

Germany: Mercedes-Benz, BMW, Audi, Porsche, Volkswagen
Italy: Ferrari, Lamborghini, Alfa Romeo, Maserati
UK: Jaguar, Land Rover, Aston Martin, Bentley, Rolls-Royce
France: Renault, Peugeot, Citroën, Bugatti

Asia (Extensive)

Japan: Toyota, Honda, Nissan, Mazda, Subaru, Mitsubishi
Korea: Hyundai, Kia, Genesis
China: BYD, NIO, XPeng, Geely, and 200+ manufacturers

Special Vehicle Types

Motorcycles: Harley-Davidson, Yamaha, Honda, Ducati, BMW
Commercial: Freightliner, Kenworth, Peterbilt, Mack
Buses: Blue Bird, Thomas, Gillig
Agricultural: John Deere
Electric: Tesla, Rivian, Lucid, Polestar, Fisker

Manufacturer-Specific Decoders

Currently implemented:

Mercedes-Benz: 115+ model variants with full specs
Ford: 100+ model codes including F-Series, Mustang, Explorer, Edge
GM: Chevrolet, Cadillac, Buick, GMC with RPO engine codes
Toyota/Lexus: Comprehensive model and engine coverage

Easily extensible for:

Honda, BMW, Nissan, etc.
See ADDING_DECODERS.md for implementation guide

🔍 Comparison

Current Capabilities (What We Actually Have)

Feature	Our Offline Decoder	NHTSA API (Online)	Basic WMI Only
Manufacturer	✓ 2,015+ codes	✓ All	~100-300 codes
Make	✓ All from WMI	✓ All	✓ Limited
Model	✓ Ford, GM, Toyota, Mercedes*	✓ All	✗
Year	✓ 1980-2039	✓ All	✗
Trim/Series	✓ Ford, GM, Toyota, Mercedes*	✓ All	✗
Engine Details	✓ Ford, GM, Toyota, Mercedes*	✓ All	✗
Transmission	✓ Ford, GM, Toyota, Mercedes*	✓ All	✗
Body Style	✓ Ford, GM, Toyota, Mercedes*	✓ All	✗
Drive Type	✓ Ford, GM, Toyota, Mercedes*	✓ All	✗
Plant Location	✓ Basic all	✓ Detailed	✗
Weight Specs	✓ Ford, GM, Toyota, Mercedes*	✓ All	✗
VIN Validation	✓ ISO 3779	✓	Basic
Check Digit	✓ Full validation	✓	✗
Region/Country	✓ All	✓ All	✓ Basic
Safety Data	✗	✓ NCAP ratings	✗
Works Offline	✓ Always	✗ Needs internet	✓
Speed	<1ms	200-500ms	<1ms
Free	✓	✓	✓

*Can be extended to other manufacturers by adding decoders (see ADDING_DECODERS.md)

📈 Recent Improvements

Version 2.0 (October 2025)

6x More Coverage: Increased from 311 to 2,015+ WMI codes
Fixed Year Bug: Now correctly decodes 2010+ model years
4 Manufacturer Decoders: Mercedes-Benz, Ford, GM, Toyota/Lexus with full specs
Enhanced Validation: ISO 3779 check digit verification
Extensible Architecture: Easy to add new manufacturers
Reference Data: CSV sources included for transparency

🛠️ Installation

Java

// Add as submodule
git submodule add https://github.com/Wal33D/nhtsa-vin-decoder.git modules/nhtsa-vin-decoder

// In your root settings.gradle:
include ':nhtsa-vin-decoder'
project(':nhtsa-vin-decoder').projectDir = new File(rootDir, 'modules/nhtsa-vin-decoder')

// In your app build.gradle:
implementation project(':nhtsa-vin-decoder')

// For NHTSA API support, add:
implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'

Android

// In your root settings.gradle:
include ':nhtsa-vin-decoder-android'
include ':nhtsa-vin-decoder-java'
project(':nhtsa-vin-decoder-android').projectDir = new File(rootDir, 'modules/nhtsa-vin-decoder/android/nhtsa-vin-decoder-android')
project(':nhtsa-vin-decoder-java').projectDir = new File(rootDir, 'modules/nhtsa-vin-decoder')

// In your app build.gradle:
implementation project(':nhtsa-vin-decoder-android')

// The Android module already includes Retrofit dependencies

Python

# No external dependencies for offline mode
from python.wmi_database import WMIDatabase

# For API support:
pip install requests  # Optional, uses urllib by default

📚 Documentation

ADDING_DECODERS.md - Add manufacturer-specific decoders
VIN_DECODER_RESOURCES.md - External data sources
API Reference - Complete API documentation
WMI Database - Offline database details

🔧 Extending the Decoder

Adding a New Manufacturer Decoder

See ADDING_DECODERS.md for complete guide.

Quick example for Ford:

public class FordDecoder {
    public static VehicleInfo decode(String vin) {
        // Extract model codes, engine, transmission
        // See MercedesBenzDecoder.java for reference
    }
}

Updating WMI Database

cd data/
# Edit CSV files to add new codes
python3 process_wmi.py
# Copy generated code to WMIDatabase.java

🧩 Using As a Gradle Submodule

Add this repo as a Git submodule, e.g. under modules/nhtsa-vin-decoder.
In your root settings.gradle (or settings.gradle.kts) include the project:

include ':nhtsa-vin-decoder'
project(':nhtsa-vin-decoder').projectDir = new File(rootDir, 'modules/nhtsa-vin-decoder')

In your app module build.gradle add a dependency:

implementation project(':nhtsa-vin-decoder')

If you use the online NHTSA API classes, add runtime dependencies in your app:

implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
implementation 'com.google.code.gson:gson:2.10.1'

⚡ Performance

Speed Comparison

Operation	Time	Throughput	Use Case
Offline Decode	<1ms	1,000+ VINs/sec	Real-time apps, mobile
Online Decode	200-500ms	~2-5 VINs/sec	Complete data needed
Batch Offline	0.5s/1000 VINs	2,000 VINs/sec	Fleet management
Batch Online (parallel)	10s/100 VINs	~10 VINs/sec	Background processing

Why Offline Mode is 500x Faster

Offline:  VIN → HashMap lookup → Result (0.8ms)
Online:   VIN → HTTP request → NHTSA server → Response parsing → Result (350ms)

Resource Usage

Memory: ~100KB for WMI database (2,015+ codes)
Storage: ~500KB total (includes manufacturer decoders)
CPU: Negligible (<1% for typical usage)
Network: Zero for offline mode, ~5KB per VIN for online

Real-World Performance Test

# Test: Decode 1,000 VINs
# Hardware: MacBook Pro M1, 16GB RAM

Offline mode:  0.534 seconds (1,873 VINs/sec)
Online mode:   342.8 seconds (2.9 VINs/sec)
Speedup:       642x faster

When to Use Each Mode

Use Offline Mode When:

Speed is critical (<1ms response time)
Working without internet connection
Processing large batches (1,000+ VINs)
Building mobile/embedded apps
Need basic info (manufacturer, year, region)

Use Online Mode When:

Need complete vehicle specifications
Want safety ratings and additional data
Require NCAP test results
Need detailed engine/transmission specs
Accuracy is more important than speed

🎯 Use Cases

OBD-II Apps - Vehicle context without internet
Fleet Management - Offline vehicle identification
Insurance - Quick VIN validation
Parts Lookup - Accurate model/engine matching
Automotive Tools - Professional diagnostic apps
Classic Cars - Decode vintage VINs (1980+)

🤝 Contributing

Found a missing WMI code or want to add a manufacturer decoder?

Fork the repository
Add codes to data/*.csv or create new decoder in java/io/github/vindecoder/offline/
Submit PR with test results

📄 License

MIT License - Free for commercial and non-commercial use

📧 Contact

Wal33D - aquataze@yahoo.com Repository: https://github.com/Wal33D/nhtsa-vin-decoder

🙏 Credits

NHTSA for providing the free vPIC API
WALL-E/vin-decoder for WMI CSV data
ISO for VIN standards (ISO 3779:2009)
US Department of Transportation
Claude (Anthropic) for assistance with GitHub release and PyPI publication

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
.github/workflows		.github/workflows
android		android
data		data
docs		docs
examples		examples
java/io/github/vindecoder		java/io/github/vindecoder
python		python
tests		tests
typescript		typescript
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
build.gradle		build.gradle
demo.py		demo.py
pom.xml		pom.xml
pyproject.toml		pyproject.toml
settings.gradle		settings.gradle
setup.py		setup.py

License

Wal33D/nhtsa-vin-decoder

Folders and files

Latest commit

History

Repository files navigation

NHTSA VIN Decoder

Sister Projects

⚡ Quick Start

Java - Offline Mode (No Internet Required)

Android - With Async Callbacks

Python - With NHTSA API

Python - Offline Mode

TypeScript/JavaScript - Auto-Fallback (API → Offline)

🎯 Overview

✨ Features

📁 Directory Structure

🚀 What You Get

Offline Decoding (No Internet Required)

Online Mode (Full NHTSA Data)

Looking for Recall Data?

💻 Quick Start

Java - Offline Mode (No Internet)

Java - With NHTSA API

Android - Complete Example

🧪 Testing

Java (Year Decoding Test)

Python (Year Decoding Test)

Python

📊 Offline Decoder Coverage

Global Manufacturer Support (2,015+ WMI Codes)

Manufacturer-Specific Decoders

🔍 Comparison

Current Capabilities (What We Actually Have)

📈 Recent Improvements

Version 2.0 (October 2025)

🛠️ Installation

Java

Android

Python

📚 Documentation

🔧 Extending the Decoder

Adding a New Manufacturer Decoder

Updating WMI Database

🧩 Using As a Gradle Submodule

⚡ Performance

Speed Comparison

Why Offline Mode is 500x Faster

Resource Usage

Real-World Performance Test

When to Use Each Mode

🎯 Use Cases

🤝 Contributing

📄 License

📧 Contact

🙏 Credits

🔮 Roadmap

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Contributors 2

Languages

Packages