A comprehensive GitHub Actions workflow for decoding Vehicle Identification Numbers (VINs) using the NHTSA vPIC API. This workflow provides complete vehicle information through multiple API endpoints and delivers detailed analysis reports.

• Complete VIN Decoding: Uses NHTSA's DecodeVinExtended API for comprehensive vehicle data
• Enhanced Data Collection: Parallel API calls to 5 additional NHTSA endpoints
• Data Quality Scoring: Automatic assessment of data completeness and reliability
• Webhook Triggered: Easy integration with external systems via repository dispatch
• Structured Outputs: JSON reports with detailed vehicle information and recommendations
• Error Handling: Robust retry logic and graceful failure handling
• Rate Limiting: Respects NHTSA API guidelines with built-in delays

• Quick Start
• Workflow Overview
• API Endpoints Used
• Setup Instructions
• Usage Examples
• Output Format
• Troubleshooting
• Contributing

git clone https://github.com/ntalekt/vin-decoder-workflow
cd vin-decoder-workflow

Ensure GitHub Actions is enabled in your repository settings.

Use PowerShell to trigger the workflow:

$headers = @{
    "Authorization" = "token YOUR_GITHUB_TOKEN"
    "Accept" = "application/vnd.github.v3+json"
    "Content-Type" = "application/json"
}

$body = @{
    event_type = "decode_vin"
    client_payload = @{
        vin = "WP0AA29936S715303"
    }
} | ConvertTo-Json

Invoke-RestMethod -Uri "https://github.com/ntalekt/vin-decoder-workflow/dispatches" -Method POST -Headers $headers -Body $body

Check the "Actions" tab in your GitHub repository to monitor workflow progress.

The workflow consists of three sequential jobs:

• Duration: ~30 seconds
• Purpose: Decode VIN using NHTSA DecodeVinExtended API
• Output: vin-basic-data.json
• Key Data: Make, model, year, engine, manufacturing details

• Duration: ~2-3 minutes
• Purpose: Collect additional data from 5 NHTSA APIs
• Output: vin-enhanced-data.json
• Dependencies: Requires Job 1 completion

• Duration: ~15 seconds
• Purpose: Consolidate data, validate, and generate final report
• Output: vin-complete-{VIN}-{timestamp}.json
• Dependencies: Requires Job 2 completion

• GitHub repository with Actions enabled
• GitHub Personal Access Token with repo scope
• PowerShell (for triggering workflows)

The workflow uses these environment variables:

env:
  NHTSA_API_BASE: "https://vpic.nhtsa.dot.gov/api/vehicles"

All necessary files are included in this repository:

vin-decoder-workflow/
├── .github/workflows/vin-decode.yml    # Main workflow
├── scripts/
│   ├── decode_vin.py                   # Primary decode script
│   ├── enhance_data.py                 # Enhancement script
│   ├── finalize_data.py                # Final processing script
│   ├── utils.py                        # Utility functions
│   └── requirements.txt                # Python dependencies
├── data/schemas/
│   └── vin_data_schema.json           # JSON validation schema
└── README.md                          # This file

# Decode a 2006 Porsche 911
$vin = "WP0AA29936S715303"
$body = @{
    event_type = "decode_vin"
    client_payload = @{ vin = $vin }
} | ConvertTo-Json

Invoke-RestMethod -Uri $webhookUrl -Method POST -Headers $headers -Body $body

# Process multiple VINs
$vins = @(
    "WP0AA29936S715303",
    "1HGCM82633A123456",
    "5NPE34AF4EH123456"
)

foreach ($vin in $vins) {
    $body = @{
        event_type = "decode_vin"
        client_payload = @{ vin = $vin }
    } | ConvertTo-Json

    Invoke-RestMethod -Uri $webhookUrl -Method POST -Headers $headers -Body $body
    Start-Sleep -Seconds 10  # Prevent rate limiting
}

{
  "report_metadata": {
    "vin": "WP0AA29936S715303",
    "report_type": "Complete VIN Analysis",
    "generated_at": "2025-09-14T15:30:45.123Z",
    "data_sources": ["NHTSA vPIC DecodeVinExtended", "NHTSA vPIC Enhancement APIs"],
    "workflow_version": "1.0"
  },
  "vehicle_summary": {
    "vin": "WP0AA29936S715303",
    "make": "PORSCHE",
    "model": "911",
    "model_year": "2006",
    "manufacturer": "DR. ING. H.C.F. PORSCHE AG",
    "body_class": "Coupe",
    "engine_cylinders": "6",
    "displacement_l": "3.6",
    "fuel_type": "Gasoline",
    "plant_city": "STUTTGART-ZUFFENHAUSEN",
    "plant_country": "GERMANY",
    "drive_type": "4x2"
  },
  "processing_information": {
    "final_processing_timestamp": "2025-09-14T15:33:12.456Z",
    "api_success_rate": "100.0%",
    "data_quality_score": 95.8,
    "successful_api_calls": 6,
    "total_api_calls": 6
  },
  "detailed_data": {
    "basic_decode": { /* Full DecodeVinExtended response */ },
    "enhanced_decode": { /* All enhancement API responses */ }
  },
  "recommendations": {
    "data_completeness": [],
    "vehicle_insights": ["Vehicle is 19 years old - may have limited parts availability"],
    "potential_issues": []
  }
}

The workflow calculates a data quality score (0-100%) based on:

• Basic Data Completeness (60%): Essential fields from primary decode
• Enhancement Success (40%): Success rate of additional API calls

Error: VIN must be exactly 17 characters

Solution: Ensure VIN is exactly 17 alphanumeric characters (excluding I, O, Q).

Request failed: HTTP 429 Too Many Requests

Solution: The workflow includes built-in 3-second delays. For batch processing, add delays between workflow triggers.

Error: Bad credentials

Solution: Verify your GitHub token has repo scope and is correctly formatted.

Check:

• Repository has Actions enabled
• Webhook URL is correct
• Token permissions are sufficient
• Event type matches (decode_vin)

Enable debug logging by setting the ACTIONS_RUNNER_DEBUG secret to true in repository settings.

Workflow logs are available in:

• Repository → Actions tab → Select workflow run → View logs

• 3-second delays between API calls
• Exponential backoff on failures
• Maximum 3 retry attempts per call

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make changes and test thoroughly
4. Commit changes: git commit -am 'Add feature'
5. Push to branch: git push origin feature-name
6. Submit a Pull Request

# Install dependencies
pip install -r scripts/requirements.txt

# Run tests locally
python scripts/decode_vin.py WP0AA29936S715303

This project is licensed under the MIT License - see the LICENSE file for details.

• NHTSA vPIC API: Vehicle data provided by the National Highway Traffic Safety Administration
• GitHub Actions: Workflow automation platform
• Python Community: Libraries and tools used in this project

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: This README and inline code comments

Note: This workflow uses free NHTSA government data and respects their API usage guidelines. No API keys or paid services required.