/nhtsa-api-wrapper

Decode and Validate Vehicle VINs - Javascript Client Wrapper for the nhtsa.dot.gov VPIC Vehicles API.

Primary LanguageTypeScriptMIT LicenseMIT

@shaggytools/nhtsa-api-wrapper Monorepo

Javascript Wrapper and Helper Functions for the NHTSA VPIC API

A universal (browser/server) javascript wrapper for the National Highway Traffic Safety Administration (NHTSA) Vehicle Information API (VPIC).

The VPIC API is primarily used for decoding useful information from a Vehicle Identification Number (VIN) in the United States and Canada. It can also be used to get all models of a make, to decode WMIs, get all makes for a certain year, and more.

Built With:

Full Documentation

https://vpic.shaggytech.com/

Mono Repo Structure

├── apps
│   ├── docs (Package Documentation)
|
├── config (Shared Configs)
│   ├── eslint-config-custom
│   ├── prettier-config
│   ├── tsconfig
│   ├── typedoc-config
|
├── packages
│   ├── lib (@shaggytools/nhtsa-api-wrapper)

Node Install

NPM

$ npm install @shaggytools/nhtsa-api-wrapper

Yarn

$ yarn add @shaggytools/nhtsa-api-wrapper

Pnpm

$ pnpm add @shaggytools/nhtsa-api-wrapper

Node Quick Start

Decoding a VIN is as easy as importing the DecodeVinValues function and calling it with a VIN.

Make sure to first install via your favorite package manager or use a CDN.

import { DecodeVinValues } from "@shaggytools/nhtsa-api-wrapper";

const results = await DecodeVinValues("WA1A4AFY2J2008189");

/* 
results = {
  Count: 136, - number of Results objects returned
  Message: 'Results returned successfully ...',
  SearchCriteria: 'VIN:WA1A4AFY2J2008189',
  Results: [ {...} ] - an array with single object of type DecodeVinValuesResults
}
*/

/* You can also use destructuring to get the Results object */
const { Results } = await DecodeVinValues("WA1A4AFY2J2008189");

/* This endpoint only returns a single object in the Results array
   The first object in the array is the decoded VIN data */
const decodedVehicle = Results[0]; // equals an object of type DecodeVinValuesResults

For a full example response see: DecodeVinValues

All available endpoints can be found here: VPIC API Endpoints

Browser Install

You can use the package directly in html script tags using a CDN. There are several options for CDN providers.

For targeting modern browsers, you can use the ESM versions with <script type="module"> and import statements.

For older browsers, you can use the IIFE versions with <script src="https://..."> to import the package. Then use the package in a separate html script via the browser global NHTSA. This global variable is only available when using the IIFE or UMD versions.

UNPKG CDN

All package files and types are hosted on the UNPKG CDN found here:

https://www.unpkg.com/@shaggytools/nhtsa-api-wrapper/

jsDelivr CDN

Homepage: https://www.jsdelivr.com/package/npm/@shaggytools/nhtsa-api-wrapper

Browser Quick Start

The following examples use the jsDelivr CDN:

ESM:

_~ 4kB (auto minified)_

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  </head>

  <body>
    <h1>ESM Example</h1>
  </body>

  <script type="module">
    // import the entire package as a single object called NHTSA
    import NHTSA from "https://cdn.jsdelivr.net/npm/@shaggytools/nhtsa-api-wrapper/+esm";
    // log to see all exported functions
    console.log(NHTSA);

    // OR import individual functions as needed
    import { DecodeVinValues } from "https://cdn.jsdelivr.net/npm/@shaggytools/nhtsa-api-wrapper/+esm";
    // Decode a VIN and log the results
    const { Results } = await DecodeVinValues("11111111111111111");
    console.log("Results", Results[0]);
  </script>
</html>

IIFE:

_~ 4kB (auto minified)_

IIFE browser global variable: NHTSA

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <!-- Import via jsDelivr CDN -->
    <script
      src="https://cdn.jsdelivr.net/npm/@shaggytools/nhtsa-api-wrapper"
    ></script>
  </head>

  <body>
    <btn id="DecodeVinValues"
      >Click to use DecodeVinValues()</btn
    >
    </br>
    Results:
    <div id="DecodeVinValuesResults"></div>
  </body>

  <!-- Use the package in a separate script -->
  <script>
    // log the browser global NHTSA to see all exported functions
    console.log(NHTSA)

    // add click handler to a button that uses the DecodeVinValues() function
    document
      .getElementById("DecodeVinValues")
      .addEventListener("click", async function () {
        const response = await NHTSA.DecodeVinValues("3VWD07AJ5EM388202").catch(
          (err) => err
        );

        // log the VPIC response
        console.log('VPIC Response: ', response);

        // add the decoded VIN results to the DOM
        document.getElementById("DecodeVinValuesResults").innerText =
          JSON.stringify(response.Results[0]);
      });
  </script>
</html>

List of Exported Functions

import {
  // NHTSA API Endpoints
  DecodeVin,
  DecodeVinExtended,
  DecodeVinValues,
  DecodeVinValuesBatch,
  DecodeVinValuesExtended,
  DecodeWMI,
  GetAllMakes,
  GetAllManufacturers,
  GetCanadianVehicleSpecifications,
  GetEquipmentPlantCodes,
  GetMakeForManufacturer,
  GetMakesForManufacturerAndYear,
  GetMakesForVehicleType,
  GetManufacturerDetails,
  GetModelsForMake,
  GetModelsForMakeId,
  GetModelsForMakeIdYear,
  GetModelsForMakeYear,
  GetParts,
  GetVehicleTypesForMake,
  GetVehicleTypesForMakeId,
  GetVehicleVariableList,
  GetVehicleVariableValuesList,
  GetWMIsForManufacturer,
  // composable function returning helper functions for NHTSA API
  useNHTSA,
  // function for offline VIN validation
  isValidVin,
} from "@shaggytools/nhtsa-api-wrapper";