sashalenz/nhtsa-api

NHTSA vPIC API for Laravel

A small, typed Laravel integration for the NHTSA vPIC API. It decodes VINs and WMIs into predictable DTOs, with built-in retries, optional proxying, and opt-in request-history logging.

Requirements

• PHP 8.4 or 8.5
• Laravel 12 or 13

Installation

composer require sashalenz/nhtsa-api

The service provider and the NhtsaApi facade are auto-discovered. Publish the config only if you need to change the defaults:

php artisan vendor:publish --tag="nhtsa-api-config"

Configuration

config/nhtsa-api.php:

Usage

Every call goes through the NhtsaApi facade and accepts a request DTO.

Decode a VIN — flat key/value (recommended)

decodeVinValues returns one result keyed by NHTSA variable name. It is the most convenient shape for reading individual fields:

use Sashalenz\NhtsaApi\Data\Requests\DecodeVinRequestData;
use Sashalenz\NhtsaApi\Facades\NhtsaApi;

$result = NhtsaApi::decodeVinValues(
    DecodeVinRequestData::from(['vin' => '58ADA1C18MU003613'])
)->firstResult();

$make = $result?->get('Make');         // "LEXUS"
$model = $result?->get('Model');       // "ES"
$body = $result?->get('BodyClass');    // "Sedan/Saloon"
$year = $result?->get('ModelYear');    // "2021"
$fuel = $result?->get('FuelTypePrimary');

get() accepts a default: $result->get('Trim', 'n/a'). Use ->results() to iterate every result row.

Decode a VIN — variable list

decodeVin returns the classic NHTSA variable list as VinDecodedVariableData items (variable, value, valueId, variableId):

$response = NhtsaApi::decodeVin(DecodeVinRequestData::from([
    'vin' => '5UXWX7C5*BA',
    'modelYear' => 2011, // optional, narrows ambiguous VIN patterns
]));

$make = $response->variables()->firstWhere('variable', 'Make')?->value;

Decode a WMI

use Sashalenz\NhtsaApi\Data\Requests\DecodeWmiRequestData;

$wmi = NhtsaApi::decodeWmi(DecodeWmiRequestData::from(['wmi' => '5UX']));

Façade methods

Service layer (request history)

NhtsaApiService wraps the client and logs every decode to the nhtsa_api_requests table — VIN, vehicle descriptor, make, model, model year, the raw decoded values, and a polymorphic link to the initiator.

use Sashalenz\NhtsaApi\Data\Requests\DecodeVinRequestData;
use Sashalenz\NhtsaApi\Services\NhtsaApiService;

$service = app(NhtsaApiService::class);

// Resolve just the make (and log the request, optionally attributed to a model).
$make = $service->determineMake(
    DecodeVinRequestData::from(['vin' => 'WP0AA2A7GL', 'modelYear' => 2016]),
    initiator: $user, // optional
);

// Full flat decode, logged.
$response = $service->decodeVinWithHistory(
    DecodeVinRequestData::from(['vin' => 'WP0AA2A7GL'])
);

// How many times this VIN has been looked up.
$count = $service->getVinRequestCount('WP0AA2A7GL');

Run the package migration to create the history table:

php artisan migrate

Error handling

A non-2xx response (after the configured retries are exhausted) raises NhtsaApiRequestException:

use Sashalenz\NhtsaApi\Exceptions\NhtsaApiRequestException;

try {
    NhtsaApi::decodeVin(DecodeVinRequestData::from(['vin' => $vin]));
} catch (NhtsaApiRequestException $e) {
    // vPIC was unavailable — fall back to manual entry, queue a retry, etc.
}

Testing

The client is built on Laravel's HTTP client, so Http::fake() intercepts every request in your tests:

use Illuminate\Support\Facades\Http;

Http::fake([
    '*/DecodeVinValues/*' => Http::response([
        'Count' => 1,
        'Message' => 'Results returned successfully',
        'Results' => [['Make' => 'LEXUS', 'Model' => 'ES']],
    ]),
]);

Run the package's own suite:

vendor/bin/pest

License

The MIT License (MIT). See LICENSE for details.