{"id":31556249,"url":"https://github.com/wal33d/nhtsa-vin-decoder","last_synced_at":"2026-04-13T09:31:53.686Z","repository":{"id":316084450,"uuid":"1061904006","full_name":"Wal33D/nhtsa-vin-decoder","owner":"Wal33D","description":"Official NHTSA vPIC API wrapper with offline WMI database fallback. Decodes VINs using government data for complete vehicle specs. Features 2000+ manufacturer codes for offline operation. Zero dependencies Python implementation.","archived":false,"fork":false,"pushed_at":"2025-10-20T07:54:14.000Z","size":239,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-20T09:38:34.458Z","etag":null,"topics":["android","automotive","automotive-software","java","nhtsa","nhtsa-api","python","vehicle-data","vehicle-identification","vin","vin-decoder","wmi"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Wal33D.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T14:39:31.000Z","updated_at":"2025-10-20T07:54:18.000Z","dependencies_parsed_at":"2025-10-20T09:20:33.603Z","dependency_job_id":"c9c4f75c-11c1-426b-b0c1-b4a7287316a2","html_url":"https://github.com/Wal33D/nhtsa-vin-decoder","commit_stats":null,"previous_names":["wal33d/nhtsa-vin-decoder"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Wal33D/nhtsa-vin-decoder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fnhtsa-vin-decoder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fnhtsa-vin-decoder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fnhtsa-vin-decoder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fnhtsa-vin-decoder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Wal33D","download_url":"https://codeload.github.com/Wal33D/nhtsa-vin-decoder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fnhtsa-vin-decoder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31746294,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","automotive","automotive-software","java","nhtsa","nhtsa-api","python","vehicle-data","vehicle-identification","vin","vin-decoder","wmi"],"created_at":"2025-10-04T22:50:58.535Z","updated_at":"2026-04-13T09:31:53.679Z","avatar_url":"https://github.com/Wal33D.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NHTSA VIN Decoder\n\n[![Build Status](https://github.com/Wal33D/nhtsa-vin-decoder/workflows/CI/badge.svg)](https://github.com/Wal33D/nhtsa-vin-decoder/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Java](https://img.shields.io/badge/Java-11+-orange.svg)](https://www.oracle.com/java/)\n[![Android](https://img.shields.io/badge/Android-API%2021+-green.svg)](https://developer.android.com/)\n[![Python](https://img.shields.io/badge/Python-3.6+-blue.svg)](https://www.python.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-14+-green.svg)](https://nodejs.org/)\n\nWorld-class VIN decoder with comprehensive offline database (2,015+ WMI codes) and NHTSA vPIC API integration\n\n## Sister Projects\n\nPart of the NHTSA automotive diagnostic toolkit:\n\n- **[nhtsa-vin-decoder](https://github.com/Wal33D/nhtsa-vin-decoder)** - This project (VIN decoder)\n- **[nhtsa-recall-lookup](https://github.com/Wal33D/nhtsa-recall-lookup)** - Look up safety recalls using decoded vehicle info\n- **[dtc-database](https://github.com/Wal33D/dtc-database)** - Comprehensive OBD-II diagnostic trouble code database\n\n**Workflow:** Decode VIN → Get vehicle info → Look up recalls → Decode diagnostic codes\n\n## ⚡ Quick Start\n\n### Java - Offline Mode (No Internet Required)\n```java\nimport io.github.vindecoder.offline.OfflineVINDecoder;\nimport io.github.vindecoder.nhtsa.VehicleData;\n\nOfflineVINDecoder decoder = new OfflineVINDecoder();\nVehicleData vehicle = decoder.decode(\"1HGCM82633A004352\");\n\nSystem.out.println(vehicle.getModelYear() + \" \" +\n                   vehicle.getMake() + \" \" +\n                   vehicle.getModel());\n// Output: 2003 Honda Accord\n```\n\n### Android - With Async Callbacks\n```java\nimport io.github.vindecoder.android.VINDecoderAndroid;\nimport io.github.vindecoder.nhtsa.VehicleData;\n\nVINDecoderAndroid decoder = new VINDecoderAndroid(context);\ndecoder.decodeAsync(\"1HGCM82633A004352\", new VINDecoderAndroid.DecodeCallback() {\n    @Override\n    public void onSuccess(VehicleData vehicle) {\n        // Called on main thread\n        Log.d(\"VIN\", vehicle.getModelYear() + \" \" + vehicle.getMake());\n        // Output: 2003 Honda\n    }\n\n    @Override\n    public void onError(String error) {\n        Log.e(\"VIN\", \"Decode failed: \" + error);\n    }\n});\n```\n\n### Python - With NHTSA API\n```python\nfrom python.nhtsa_vin_decoder import NHTSAVinDecoder\n\ndecoder = NHTSAVinDecoder()\nvehicle = decoder.decode(\"1HGCM82633A004352\")\n\nprint(f\"{vehicle.year} {vehicle.make} {vehicle.model}\")\n# Output: 2003 Honda Accord\n```\n\n### Python - Offline Mode\n```python\nfrom python.wmi_database import WMIDatabase\n\nmanufacturer = WMIDatabase.get_manufacturer(\"1HGCM82633A004352\")\nyear = WMIDatabase.get_year(\"1HGCM82633A004352\")\n\nprint(f\"{year} {manufacturer}\")\n# Output: 2003 Honda\n```\n\n### TypeScript/JavaScript - Auto-Fallback (API → Offline)\n```typescript\nimport { VINDecoder } from '@wal33d/nhtsa-vin-decoder';\n\n// Default: Tries NHTSA API first, falls back to offline WMI database\nconst decoder = new VINDecoder();\nconst vehicle = await decoder.decode('1HGCM82633A004352');\nconsole.log(`${vehicle.make} ${vehicle.model} ${vehicle.bodyClass}`);\n// Output: Honda Accord Sedan (from API)\n// Falls back to offline if API unavailable\n\n// Force offline-only mode\nconst offlineDecoder = new VINDecoder({ online: false });\nconst offlineData = await offlineDecoder.decode('1HGCM82633A004352');\nconsole.log(`${offlineData.modelYear} ${offlineData.manufacturer}`);\n// Output: 2003 Honda (from WMI database)\n```\n\n## 🎯 Overview\n\nAdvanced 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**.\n\n## ✨ Features\n\n- **Enhanced Offline Decoder** - Full VIN decoding without internet\n- **2,015+ Manufacturer Codes** - Comprehensive WMI database (6x industry standard)\n- **Manufacturer-Specific Decoders** - Detailed model/trim/engine extraction\n- **VIN Validation** - Check digit verification per ISO 3779\n- **Year Decoding** - Accurate model year extraction (1980-2039)\n- **Official NHTSA API** - Falls back to government database when online\n- **Automatic Fallback** - Seamlessly switches between offline/online\n- **FREE** - No API key required\n- **Caching** - Built-in LRU cache to reduce API calls\n- **Multi-platform** - Java, Android, Python, and TypeScript/JavaScript implementations\n\n## 📁 Directory Structure\n\n```\nnhtsa-vin-decoder/\n├── java/io/github/vindecoder/\n│   ├── offline/                    # Offline decoder implementation\n│   │   ├── OfflineVINDecoder.java  # Main offline decoder\n│   │   ├── VINValidator.java       # VIN validation \u0026 structure\n│   │   ├── WMIDatabase.java        # 948+ manufacturer codes\n│   │   └── MercedesBenzDecoder.java # Example manufacturer decoder\n│   └── nhtsa/                      # NHTSA API integration\n│       ├── VINDecoderService.java\n│       ├── VehicleData.java\n│       └── NHTSAApiService.java\n├── android/                        # Android wrapper library\n│   └── nhtsa-vin-decoder-android/\n│       └── src/main/java/io/github/vindecoder/android/\n│           └── VINDecoderAndroid.java  # Android-friendly async API\n├── python/                         # Python implementation\n│   ├── nhtsa_vin_decoder.py       # Main decoder with API\n│   └── wmi_database.py            # Offline WMI database\n├── data/                          # Reference data (not used at runtime)\n│   ├── *.csv                      # Source WMI data from WALL-E/vin-decoder\n│   ├── process_wmi.py             # Script to regenerate database\n│   └── wmi_database_generated.java # Generated code\n└── docs/                          # Documentation\n    ├── ADDING_DECODERS.md        # Guide for adding manufacturers\n    ├── VIN_DECODER_RESOURCES.md  # External data sources\n    ├── API.md                    # Complete API reference\n    ├── INSTALLATION.md           # Setup guide\n    ├── USAGE.md                  # Examples and best practices\n    └── WMI_DATABASE.md          # Offline database details\n```\n\n## 🚀 What You Get\n\n### Offline Decoding (No Internet Required)\n```json\n{\n  \"vin\": \"4JGDA5HB7JB158144\",\n  \"make\": \"Mercedes-Benz\",\n  \"manufacturer\": \"Mercedes-Benz (Daimler AG)\",\n  \"model\": \"GLE-Class\",\n  \"year\": \"2018\",\n  \"trim\": \"GLE 350 4MATIC\",\n  \"vehicle_type\": \"Sport Utility Vehicle (SUV)\",\n  \"body_class\": \"Sport Utility Vehicle (SUV)\",\n  \"doors\": \"4\",\n  \"drive_type\": \"4MATIC\",\n  \"engine_model\": \"3.5L V6\",\n  \"engine_cylinders\": \"6\",\n  \"engine_displacement_l\": \"3.5\",\n  \"fuel_type\": \"Gasoline\",\n  \"transmission_style\": \"Automatic\",\n  \"transmission_speeds\": \"9\",\n  \"plant_city\": \"Tuscaloosa\",\n  \"plant_state\": \"Alabama\",\n  \"plant_country\": \"United States\",\n  \"gvwr\": \"6062\",\n  \"curb_weight\": \"4630\"\n}\n```\n\n### Online Mode (Full NHTSA Data)\nAll of the above PLUS safety ratings, NCAP data, and more.\n\n### Looking for Recall Data?\nFor vehicle recall information, check out our sister project: [NHTSA Recall Lookup](https://github.com/Wal33D/nhtsa-recall-lookup)\n\n## 💻 Quick Start\n\n### Java - Offline Mode (No Internet)\n```java\nimport io.github.vindecoder.offline.OfflineVINDecoder;\nimport io.github.vindecoder.nhtsa.VehicleData;\n\nOfflineVINDecoder decoder = new OfflineVINDecoder();\nVehicleData vehicle = decoder.decode(\"4JGDA5HB7JB158144\");\n\nSystem.out.println(\"Vehicle: \" + vehicle.getModelYear() + \" \" +\n                   vehicle.getMake() + \" \" + vehicle.getModel());\n// Output: Vehicle: 2018 Mercedes-Benz GLE-Class\n\nSystem.out.println(\"Trim: \" + vehicle.getTrim());\n// Output: Trim: GLE 350 4MATIC\n\nSystem.out.println(\"Engine: \" + vehicle.getEngineModel());\n// Output: Engine: 3.5L V6\n```\n\n### Java - With NHTSA API\n```java\nVINDecoderService decoder = VINDecoderService.getInstance();\n\ndecoder.decodeVIN(\"4JGDA5HB7JB158144\", new VINDecoderCallback() {\n    @Override\n    public void onSuccess(VehicleData vehicle) {\n        // Full NHTSA data returned\n        System.out.println(\"Vehicle: \" + vehicle.getDisplayName());\n    }\n\n    @Override\n    public void onError(String error) {\n        // Automatically falls back to offline decoder\n        VehicleData vehicle = new OfflineVINDecoder().decode(vin);\n    }\n});\n```\n\n### Android - Complete Example\n```java\nimport io.github.vindecoder.android.VINDecoderAndroid;\nimport io.github.vindecoder.nhtsa.VehicleData;\n\npublic class MainActivity extends AppCompatActivity {\n    private VINDecoderAndroid decoder;\n\n    @Override\n    protected void onCreate(Bundle savedInstanceState) {\n        super.onCreate(savedInstanceState);\n        decoder = new VINDecoderAndroid(this);\n\n        // Async decode with main thread callbacks\n        decoder.decodeAsync(\"4JGDA5HB7JB158144\", new VINDecoderAndroid.DecodeCallback() {\n            @Override\n            public void onSuccess(VehicleData vehicle) {\n                // Safe to update UI - callback runs on main thread\n                textView.setText(vehicle.getModelYear() + \" \" +\n                               vehicle.getMake() + \" \" +\n                               vehicle.getModel());\n            }\n\n            @Override\n            public void onError(String error) {\n                Toast.makeText(MainActivity.this, error, Toast.LENGTH_SHORT).show();\n            }\n        });\n\n        // Or use synchronous methods on background thread\n        new Thread(() -\u003e {\n            VehicleData vehicle = decoder.decode(\"4JGDA5HB7JB158144\");\n            runOnUiThread(() -\u003e {\n                // Update UI\n            });\n        }).start();\n    }\n}\n```\n\n## 🧪 Testing\n\n### Java (Year Decoding Test)\n- Using Gradle (recommended):\n```\n./gradlew test\n```\nThis runs JUnit tests validating VIN model year decoding across the 30-year cycle, including 2031–2039 (digit codes with position 7 letter heuristic).\n\n### Python (Year Decoding Test)\n- Run tests:\n```\npython3 tests/test_year.py\n```\n\nThis validates the Python WMI fallback year-decoding heuristic matches the Java logic.\n\n### Python\n```python\nfrom python.nhtsa_vin_decoder import NHTSAVinDecoder\n\ndecoder = NHTSAVinDecoder()\nvehicle = decoder.decode(\"4JGDA5HB7JB158144\")\n\nprint(f\"Vehicle: {vehicle.year} {vehicle.make} {vehicle.model}\")\n# Output: Vehicle: 2018 Mercedes-Benz GLE-Class\n```\n\n## 📊 Offline Decoder Coverage\n\n### Global Manufacturer Support (2,015+ WMI Codes)\n\n**North America** (Complete)\n- United States: Ford, GM, Tesla, Rivian, Lucid\n- Canada: All manufacturers\n- Mexico: All manufacturers\n\n**Europe** (Comprehensive)\n- Germany: Mercedes-Benz, BMW, Audi, Porsche, Volkswagen\n- Italy: Ferrari, Lamborghini, Alfa Romeo, Maserati\n- UK: Jaguar, Land Rover, Aston Martin, Bentley, Rolls-Royce\n- France: Renault, Peugeot, Citroën, Bugatti\n\n**Asia** (Extensive)\n- Japan: Toyota, Honda, Nissan, Mazda, Subaru, Mitsubishi\n- Korea: Hyundai, Kia, Genesis\n- China: BYD, NIO, XPeng, Geely, and 200+ manufacturers\n\n**Special Vehicle Types**\n- Motorcycles: Harley-Davidson, Yamaha, Honda, Ducati, BMW\n- Commercial: Freightliner, Kenworth, Peterbilt, Mack\n- Buses: Blue Bird, Thomas, Gillig\n- Agricultural: John Deere\n- Electric: Tesla, Rivian, Lucid, Polestar, Fisker\n\n### Manufacturer-Specific Decoders\n\nCurrently implemented:\n- **Mercedes-Benz**: 115+ model variants with full specs\n- **Ford**: 100+ model codes including F-Series, Mustang, Explorer, Edge\n- **GM**: Chevrolet, Cadillac, Buick, GMC with RPO engine codes\n- **Toyota/Lexus**: Comprehensive model and engine coverage\n\nEasily extensible for:\n- Honda, BMW, Nissan, etc.\n- See [ADDING_DECODERS.md](docs/ADDING_DECODERS.md) for implementation guide\n\n## 🔍 Comparison\n\n### Current Capabilities (What We Actually Have)\n\n| Feature | Our Offline Decoder | NHTSA API (Online) | Basic WMI Only |\n|---------|-------------------|-------------------|----------------|\n| **Manufacturer** | ✓ 2,015+ codes | ✓ All | ~100-300 codes |\n| **Make** | ✓ All from WMI | ✓ All | ✓ Limited |\n| **Model** | ✓ Ford, GM, Toyota, Mercedes* | ✓ All | ✗ |\n| **Year** | ✓ 1980-2039 | ✓ All | ✗ |\n| **Trim/Series** | ✓ Ford, GM, Toyota, Mercedes* | ✓ All | ✗ |\n| **Engine Details** | ✓ Ford, GM, Toyota, Mercedes* | ✓ All | ✗ |\n| **Transmission** | ✓ Ford, GM, Toyota, Mercedes* | ✓ All | ✗ |\n| **Body Style** | ✓ Ford, GM, Toyota, Mercedes* | ✓ All | ✗ |\n| **Drive Type** | ✓ Ford, GM, Toyota, Mercedes* | ✓ All | ✗ |\n| **Plant Location** | ✓ Basic all | ✓ Detailed | ✗ |\n| **Weight Specs** | ✓ Ford, GM, Toyota, Mercedes* | ✓ All | ✗ |\n| **VIN Validation** | ✓ ISO 3779 | ✓ | Basic |\n| **Check Digit** | ✓ Full validation | ✓ | ✗ |\n| **Region/Country** | ✓ All | ✓ All | ✓ Basic |\n| **Safety Data** | ✗ | ✓ NCAP ratings | ✗ |\n| **Works Offline** | ✓ Always | ✗ Needs internet | ✓ |\n| **Speed** | \u003c1ms | 200-500ms | \u003c1ms |\n| **Free** | ✓ | ✓ | ✓ |\n\n*Can be extended to other manufacturers by adding decoders (see [ADDING_DECODERS.md](docs/ADDING_DECODERS.md))\n\n## 📈 Recent Improvements\n\n### Version 2.0 (October 2025)\n- **6x More Coverage**: Increased from 311 to 2,015+ WMI codes\n- **Fixed Year Bug**: Now correctly decodes 2010+ model years\n- **4 Manufacturer Decoders**: Mercedes-Benz, Ford, GM, Toyota/Lexus with full specs\n- **Enhanced Validation**: ISO 3779 check digit verification\n- **Extensible Architecture**: Easy to add new manufacturers\n- **Reference Data**: CSV sources included for transparency\n\n## 🛠️ Installation\n\n### Java\n```gradle\n// Add as submodule\ngit submodule add https://github.com/Wal33D/nhtsa-vin-decoder.git modules/nhtsa-vin-decoder\n\n// In your root settings.gradle:\ninclude ':nhtsa-vin-decoder'\nproject(':nhtsa-vin-decoder').projectDir = new File(rootDir, 'modules/nhtsa-vin-decoder')\n\n// In your app build.gradle:\nimplementation project(':nhtsa-vin-decoder')\n\n// For NHTSA API support, add:\nimplementation 'com.squareup.retrofit2:retrofit:2.9.0'\nimplementation 'com.squareup.retrofit2:converter-gson:2.9.0'\n```\n\n### Android\n```gradle\n// In your root settings.gradle:\ninclude ':nhtsa-vin-decoder-android'\ninclude ':nhtsa-vin-decoder-java'\nproject(':nhtsa-vin-decoder-android').projectDir = new File(rootDir, 'modules/nhtsa-vin-decoder/android/nhtsa-vin-decoder-android')\nproject(':nhtsa-vin-decoder-java').projectDir = new File(rootDir, 'modules/nhtsa-vin-decoder')\n\n// In your app build.gradle:\nimplementation project(':nhtsa-vin-decoder-android')\n\n// The Android module already includes Retrofit dependencies\n```\n\n### Python\n```python\n# No external dependencies for offline mode\nfrom python.wmi_database import WMIDatabase\n\n# For API support:\npip install requests  # Optional, uses urllib by default\n```\n\n## 📚 Documentation\n\n- [ADDING_DECODERS.md](docs/ADDING_DECODERS.md) - Add manufacturer-specific decoders\n- [VIN_DECODER_RESOURCES.md](docs/VIN_DECODER_RESOURCES.md) - External data sources\n- [API Reference](docs/API.md) - Complete API documentation\n- [WMI Database](docs/WMI_DATABASE.md) - Offline database details\n\n## 🔧 Extending the Decoder\n\n### Adding a New Manufacturer Decoder\nSee [ADDING_DECODERS.md](docs/ADDING_DECODERS.md) for complete guide.\n\nQuick example for Ford:\n```java\npublic class FordDecoder {\n    public static VehicleInfo decode(String vin) {\n        // Extract model codes, engine, transmission\n        // See MercedesBenzDecoder.java for reference\n    }\n}\n```\n\n### Updating WMI Database\n```bash\ncd data/\n# Edit CSV files to add new codes\npython3 process_wmi.py\n# Copy generated code to WMIDatabase.java\n```\n\n## 🧩 Using As a Gradle Submodule\n\n- Add this repo as a Git submodule, e.g. under `modules/nhtsa-vin-decoder`.\n- In your root `settings.gradle` (or `settings.gradle.kts`) include the project:\n```\ninclude ':nhtsa-vin-decoder'\nproject(':nhtsa-vin-decoder').projectDir = new File(rootDir, 'modules/nhtsa-vin-decoder')\n```\n- In your app module `build.gradle` add a dependency:\n```\nimplementation project(':nhtsa-vin-decoder')\n```\n- If you use the online NHTSA API classes, add runtime dependencies in your app:\n```\nimplementation 'com.squareup.retrofit2:retrofit:2.9.0'\nimplementation 'com.squareup.retrofit2:converter-gson:2.9.0'\nimplementation 'com.google.code.gson:gson:2.10.1'\n```\n\n## ⚡ Performance\n\n### Speed Comparison\n\n| Operation | Time | Throughput | Use Case |\n|-----------|------|------------|----------|\n| **Offline Decode** | \u003c1ms | 1,000+ VINs/sec | Real-time apps, mobile |\n| **Online Decode** | 200-500ms | ~2-5 VINs/sec | Complete data needed |\n| **Batch Offline** | 0.5s/1000 VINs | 2,000 VINs/sec | Fleet management |\n| **Batch Online (parallel)** | 10s/100 VINs | ~10 VINs/sec | Background processing |\n\n### Why Offline Mode is 500x Faster\n\n```\nOffline:  VIN → HashMap lookup → Result (0.8ms)\nOnline:   VIN → HTTP request → NHTSA server → Response parsing → Result (350ms)\n```\n\n### Resource Usage\n\n- **Memory**: ~100KB for WMI database (2,015+ codes)\n- **Storage**: ~500KB total (includes manufacturer decoders)\n- **CPU**: Negligible (\u003c1% for typical usage)\n- **Network**: Zero for offline mode, ~5KB per VIN for online\n\n### Real-World Performance Test\n\n```python\n# Test: Decode 1,000 VINs\n# Hardware: MacBook Pro M1, 16GB RAM\n\nOffline mode:  0.534 seconds (1,873 VINs/sec)\nOnline mode:   342.8 seconds (2.9 VINs/sec)\nSpeedup:       642x faster\n```\n\n### When to Use Each Mode\n\n**Use Offline Mode When:**\n- Speed is critical (\u003c1ms response time)\n- Working without internet connection\n- Processing large batches (1,000+ VINs)\n- Building mobile/embedded apps\n- Need basic info (manufacturer, year, region)\n\n**Use Online Mode When:**\n- Need complete vehicle specifications\n- Want safety ratings and additional data\n- Require NCAP test results\n- Need detailed engine/transmission specs\n- Accuracy is more important than speed\n\n## 🎯 Use Cases\n\n- **OBD-II Apps** - Vehicle context without internet\n- **Fleet Management** - Offline vehicle identification\n- **Insurance** - Quick VIN validation\n- **Parts Lookup** - Accurate model/engine matching\n- **Automotive Tools** - Professional diagnostic apps\n- **Classic Cars** - Decode vintage VINs (1980+)\n\n## 🤝 Contributing\n\nFound a missing WMI code or want to add a manufacturer decoder?\n1. Fork the repository\n2. Add codes to `data/*.csv` or create new decoder in `java/io/github/vindecoder/offline/`\n3. Submit PR with test results\n\n## 📄 License\n\nMIT License - Free for commercial and non-commercial use\n\n## 📧 Contact\n\n**Wal33D** - aquataze@yahoo.com\n**Repository**: https://github.com/Wal33D/nhtsa-vin-decoder\n\n## 🙏 Credits\n\n- NHTSA for providing the free vPIC API\n- WALL-E/vin-decoder for WMI CSV data\n- ISO for VIN standards (ISO 3779:2009)\n- US Department of Transportation\n- Claude (Anthropic) for assistance with GitHub release and PyPI publication\n\n## 🔮 Roadmap\n\n- [x] Ford decoder (positions 4-8 patterns)\n- [x] GM/Chevrolet decoder\n- [x] Toyota/Lexus decoder\n- [ ] Honda/Acura decoder\n- [ ] BMW decoder (17-character patterns)\n- [ ] Nissan/Infiniti decoder\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwal33d%2Fnhtsa-vin-decoder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwal33d%2Fnhtsa-vin-decoder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwal33d%2Fnhtsa-vin-decoder/lists"}