@shaggytools/nhtsa-api-wrapper
Version:
Universal javascript wrapper for the NHTSA.dot.gov VPIC 'vehicles' API, useful for VIN decoding, etc.
263 lines (205 loc) • 8.56 kB
Markdown
# @shaggytools/nhtsa-api-wrapper
<p align="center">
<a href="https://www.npmjs.com/package/@shaggytools/nhtsa-api-wrapper" target="_blank">
<img src="https://img.shields.io/npm/v/@shaggytools/nhtsa-api-wrapper?style=for-the-badge">
</a>
<a href="https://github.com/ShaggyTech/nhtsa-api-wrapper/actions/workflows/ci.yml" target="_blank">
<img src="https://img.shields.io/github/actions/workflow/status/shaggytech/nhtsa-api-wrapper/ci.yml?style=for-the-badge">
</a>
<a href="https://bundlephobia.com/result?p=@shaggytools/nhtsa-api-wrapper" target="_blank">
<img src="https://img.shields.io/bundlephobia/min/@shaggytools/nhtsa-api-wrapper?style=for-the-badge">
</a>
<a href="https://bundlephobia.com/result?p=@shaggytools/nhtsa-api-wrapper" target="_blank">
<img src="https://img.shields.io/bundlephobia/minzip/@shaggytools/nhtsa-api-wrapper?style=for-the-badge">
</a>
<a href="https://codecov.io/gh/ShaggyTech/nhtsa-api-wrapper" target="_blank">
<img src="https://img.shields.io/codecov/c/github/shaggytech/nhtsa-api-wrapper/main?style=for-the-badge">
</a>
</p>
---
## Javascript Wrapper and Helper Functions for the [NHTSA VPIC API](https://vpic.nhtsa.dot.gov/api/Home)
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.
---
<div align="center" style="font-size: 1.5em; font-weight: bold;">Built With:</div>
<br>
<p align="center">
<a href="https://github.com/pnpm/pnpm" target="_blank">
<img src="https://img.shields.io/static/v1?style=for-the-badge&message=pnpm&color=222222&logo=pnpm&logoColor=F69220&label=">
</a>
<a href="https://vitejs.dev" target="_blank">
<img src="https://img.shields.io/static/v1?style=for-the-badge&message=Vite&color=646CFF&logo=Vite&logoColor=FFFFFF&label=">
</a>
<a href="https://vitepress.dev/" target="_blank">
<img src="https://img.shields.io/static/v1?style=for-the-badge&message=Vitepress&color=000000&logo=Vite&logoColor=FFFFFF&label=">
</a>
<a href="https://vitest.dev/" target="_blank">
<img src="https://img.shields.io/static/v1?style=for-the-badge&message=Vitest&color=222222&logo=Vitest&logoColor=4FC08D&label=">
</a>
<a href="https://github.com/vercel/turborepo" target="_blank">
<img src="https://img.shields.io/static/v1?style=for-the-badge&message=Turborepo%20by%20Vercel&color=000000&logo=Vercel&logoColor=FFFFFF&label=">
</a>
</p>
---
## Full Documentation
### [https://vpic.shaggytech.com/](https://vpic.shaggytech.com/)
- [Introduction](https://vpic.shaggytech.com/guide)
- [Install](https://vpic.shaggytech.com/guide/install)
- [Node Quick Start](https://vpic.shaggytech.com//guide/getting-started#node-quick-start)
- [Browser Quick Start](https://vpic.shaggytech.com/guide/getting-started#browser-quick-start)
- [API Reference](https://vpic.shaggytech.com/api/)
## Node Install
### [NPM](https://www.npmjs.com/package/@shaggytools/nhtsa-api-wrapper)
```sh [npm]
$ npm install @shaggytools/nhtsa-api-wrapper
```
### Yarn
```sh [yarn]
$ yarn add @shaggytools/nhtsa-api-wrapper
```
### Pnpm
```sh [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.
```javascript
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](https://vpic.shaggytech.com/api/endpoints/decode-vin-values#returns)
All available endpoints can be found here: [VPIC API Endpoints](https://vpic.shaggytech.com/api/#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/](https://www.unpkg.com/@shaggytools/nhtsa-api-wrapper/)
### jsDelivr CDN
Homepage: [https://www.jsdelivr.com/package/npm/@shaggytools/nhtsa-api-wrapper](https://www.jsdelivr.com/package/npm/@shaggytools/nhtsa-api-wrapper)
## Browser Quick Start
The following examples use the jsDelivr CDN:
#### ESM:
_~ 4kB (auto minified)_
```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`
```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
```javascript
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'
```