amattu2/nhtsa-wrapper

A simple PHP based NHTSA (U.S. Department of Transportation) vehicle VIN decoder and Recall lookup API wrapper.

v1.1.0 2025-03-02 18:14 UTC

Requires

• php: >=7.4
• ext-curl: *

AGPL-3.0

• Alec M.

README

This is a simple VIN decoder wrapper for the NHTSA (United States Department of Transportation) VIN decoder API. Additionally, it includes the NHTSA vehicle recall API. See usage section below or the example index.php file.

Usage

Import

Install with composer

require amattu2/nhtsa-wrapper

require "vendor/autoload.php";

VIN Decode

Raw Decode

PHPDoc

/**
 * Decode a 17-digit VIN
 *
 * @param string vin number
 * @param ?integer model year
 * @return ?array raw NHTSA result
 * @throws TypeError
 * @author Alec M. <https://amattu.com>
 * @date 2021-04-04T16:19:40-040
 */

Usage

$decode = amattu2\NHTSA\Client::decodeVIN("VIN_NUMBER");

Success return result

Array
(
  [Error Text] =>
  [Make] =>
  [Manufacturer Name] =>
  [Model] =>
  [Model Year] =>
  [Plant City] =>
  [Series] =>
  [Trim] =>
  [Vehicle Type] =>
  [Plant Country] =>
  ...
)

Pretty Decode

PHPDoc

/**
* Parse a raw decode call
* Converts a decodeVIN call into a pretty parsed Year, Make, Model, Trim, Engine array
*
* @param array raw decode result
* @return ?array pretty parsed NHTSA result
* @throws TypeError
* @author Alec M. <https://amattu.com>
* @date 2021-04-04T16:52:15-040
*/

Usage

$decode = amattu2\NHTSA\Client::decodeVIN("VIN_NUMBER");
$pretty_decode = amattu2\NHTSA\Client::parseDecode($decode);

Success return result (Example)

Array
(
  [Model_Year] => 2011
  [Make] => MERCEDES-BENZ
  [Model] => M-CLASS
  [Trim] =>  4-MATIC
  [Engine] => 3.5L 6-CYL (3,500CC)
)

Recalls

Raw Recalls

PHPDoc

/**
 * Get vehicle recalls by Year, Make, Model
 *
 * @param int model year
 * @param string make
 * @param string model
 * @return ?array NHTSA raw result
 * @throws TypeError
 * @author Alec M. <https://amattu.com>
 * @date 2021-04-04T16:48:24-040
 */

Usage

$recalls = amattu2\NHTSA\Client::getRecalls(2015, "Ford", "Mustang");

Success return result

Array
(
  [0] => Array
  (
      [Manufacturer] =>
      [NHTSACampaignNumber] =>
      [ReportReceivedDate] =>
      [Component] =>
      [Summary] =>
      [Conequence] =>
      [Remedy] =>
      [Notes] =>
      [ModelYear] =>
      [Make] =>
      [Model] =>
  )
  ...
)

Pretty Recalls

PHPDoc

/**
 * Parse a raw recall result
 *
 * @param array raw recall result
 * @return ?array parsed recall result
 * @throws TypeError
 * @author Alec M. <https://amattu.com>
 * @date 2021-04-04T18:16:26-040
*/

Usage

$recalls = amattu2\NHTSA\Client::getRecalls(2015, "Ford", "Mustang");
$pretty_recalls = amattu2\NHTSA\Client::parseRecalls($recalls);

Success return result

Array
(
  [2] => Array
  (
    [Campaign_Number] =>
    [Component] => Array
    (
      [0] => FUEL SYSTEM, GASOLINE
      [1] => STORAGE
      [2] => TANK ASSEMBLY /* The last element is the actual component */
    )
    [Date] => 2015-06-02
    [Description] =>
    [Remedy] =>
  )
  ...
)

getModelsForMakeByYear

PHPDoc

/**
 * Get all available models for a make by year
 *
 * @note This is a free-text match. Recommend using `getModelsForMakeIdByYear`
 * @param int $year The model year
 * @param string $make The make
 */

Usage

$models = amattu2\NHTSA\Client::getModelsForMakeByYear(2015, "Ford");

Success return result

Array
(
  [0] => Array
  (
    [Make_ID] => 441
    [Make_Name] => FORD
    [Model_ID] => 2021
    [Model_Name] => C-MAX
  )
  ...
)

getModelsForMakeIdByYear

PHPDoc

/**
 * Get all available models for a make by year
 *
 * @param int $year The model year
 * @param int $make_id The make ID
 */

Usage

$models = amattu2\NHTSA\Client::getModelsForMakeIdByYear(2015, 441);

Success return result

Array
(
  [0] => Array
  (
    [Make_ID] => 441
    [Make_Name] => FORD
    [Model_ID] => 2021
    [Model_Name] => C-MAX
  )
  ...
)

getModelsForMake

PHPDoc

/**
 * Get all available models for a make
 *
 * @param string $make The make
 */

Usage

$models = amattu2\NHTSA\Client::getModelsForMake("Ford");

Success return result

Array
(
  [0] => Array
  (
    [Make_ID] => 441
    [Make_Name] => FORD
    [Model_ID] => 2021
    [Model_Name] => C-MAX
  )
  ...
)

getModelsForMakeId

PHPDoc

/**
 * Get all available models for a make
 *
 * @param int $make_id The make ID
 */

Usage

$models = amattu2\NHTSA\Client::getModelsForMakeId(441);

Success return result

Array
(
  [0] => Array
  (
    [Make_ID] => 441
    [Make_Name] => FORD
    [Model_ID] => 2021
    [Model_Name] => C-MAX
  )
  ...
)

Requirements & Dependencies

• PHP 7.4+
• cURL Extension