@shaggytools / nhtsa-api-wrapper
An async NHSTA.dot.gov Vehicles API wrapper, written in Typescript and bundled with Rollup. It can be used universally in most environments (Node, browsers, scripts, modules, Webpack, Rollup, etc.).
The API that this wrapper was written for is primarily used for decoding useful information from Vehicle Identification Numbers (VINs) in the United States and Canada. However, the NHTSA Vehicles API contains a total of 24 different endpoints, or "Actions" as the developers of the API chose to call them. Within the documentation you'll see references to these "Actions" and each one will return different information based on a variety of parameters, some required and some optional. This includes decoding WMIs, Canadian VINs, models per make and year, etc.
Complete Documentation: https://www.shaggytech.com/nhtsa-api-wrapper/
If you find an issue or would like to make or suggest improvements, I would gladly welcome the feedback.
This package was developed and tested on
NPM v6.11.3, and
Table of Contents
Expand to see all available API Actions
I also wanted to further my knowledge by learning TypeScript, JSDoc, Jest, and Rollup. Thus was born this package.
I hope you find this package useful and mostly free of bugs 🐛.
cross-fetch NPM Package
- Universal WHATWG Fetch API for Node, Browsers and React Native.
- Uses whatwg-fetch in the browser and node-fetch in node environments.
How to Install and Use This Package
In Node Environments
# NPMnpm install @shaggytools/nhtsa-api-wrapper# Yarnyarn add @shaggytools/nhtsa-api-wrapper
Using in Node
Listed below, there are several ways to use this package within a Node environment.
- The first two will give you access to all 24 NHTSA endpoints within the same import.
- The last one allows you to import the individual actions if you are only interested in using one or some of them.
If you prefer not to use the
new keyword you can use the Client export, which returns a new instance of the
const Client = ;// Decode a VIN and get the complete responseconst response = await Client;console;// Get all available Makes and get only the Results arrayconst Results = await Client;console;
Via NHTSA class
You can import the NHTSA class, which is a class exported by this package that implements all of the API
Actions. You will need to instantiate the class with
const NHTSA = ;const ApiClient = ;// Get models for a specified Make + Year and get the complete responseconst response = await ApiClient;console;// Decode a VIN and get only the Results arrayconst Results = await ApiClient;console;
Via NHTSA class with configuration options
See the FetchConfig type for more information on what can be passed to the NHTSA class. This includes configuration
options for the Fetch API, such as Headers and credentials, which allow you fine control over the http request sent to the NHTSA API.
baseUrl could be useful if you want to proxy/mirror the NHTSA endpoints through your own server, or if the NHTSA URL were to change in the future and you needed an immediate way to correct it.
options is useful to pass in your own Headers, add credentials to the request, and more, if needed.
Sample code, with config options passed to the class constructor:
const NHTSA =const ApiClient =baseUrl: ''options:method: 'GET'credentials: 'same-origin';const response = ApiClient// or do something with the response here as well
Via individual API Actions
You can import individual NHTSA
Action classes if you only need to use one of them at a time, or even just a few of them. Each class has a single member method with the same name as the class. For example, the DecodeVin class has a method named
DecodeVin and is used like
DecodeVin.DecodeVin(<vin>), which is after instantiating the class with
Using the wrapper in this way can slightly reduce the imported size. It's useful to keep in mind that every Action requires the cross-fetch package as a dependency. The cross-fetch package adds approximately 8.3kB of the total size of this package.
Sample code; change
DecodeWMI to any desired NHTSA Action, or import multiples.
constDecodeWMIGetModelsForMake} = ;const Decoder = ;const GetModels = ;// Decode a VIN and return only the Results arrayconst Results = await Decoder;console;// Decode a VIN and return the complete responseconst response = await Decoder;console;// Get models per make and return only the Results arrayconst Results = await GetModels;console;
In Browser Environments
This package exports a global browser window object named
Further below, there will be full examples for how to use the
NHTSA global in different scenarios.
NHTSA.Client is an instance of the NHTSA class which implements all of the wrappers for the NHTSA Actions. You can avoid using the
new keyword in your code if you use it this way. See the Client class for more information.
NHTSA.NHTSA is the main class which implements all of the Action class methods. You will need to use the
new keyword within your code <
new NHTSA()>. See the NHTSA class for more information.
NHTSA.isValidVin is a method that takes a single string argument, a Vehicle Identification Number, and performs an offline VIN validation. It will return true if the VIN passes the algorithm, otherwise false. This can be useful if you want to ensure a valid VIN is entered by the user, which will prevent unnecessary HTTP/API requests. See the isValidVin module for more information.
In all of the following URLs either:
<version>for the most recent release
<version>to specific version number "x.x.xx"
Via jsdelivr.net CDN
Basic Usage in Browser
Via UMD universal bundle and cdn.jsdelivr.net:
<!-- Change <version> to specific version number "x.x.xx",or remove <version> for the most recent published version -->...
Full HTML example; copy and paste to try it out:
Testing UMD bundle imports<!-- Change <version> to specific version number "x.x.xx",or remove <version> for the most recent published version -->Click to console.log NHTSA.DecodeVin() results
Lazy Loaded ESModule in Browser Environments
Lazy Loading using ES Modules and unpkg.com:
Full HTML Example:
Testing lazy loaded module importsClick to console.log DecodeVin() results
NHTSA API Responses
Each action returns a response in the form of an ApiResponse object.
You'll likely only be interested in the
ApiResponse.Results portion of the response.
Results is an array that will hold one or more objects, with the number of objects depending on the specific Action that was used. There is also additional information returned about the request, response, headers etc. within the
As an example, you can see what the
GetEquipmentPlantCodes response will be by going to it's response type, located on the documentation page for the same named module, with the word "Response" added to the end.
NHTSA API Actions
There are a total of 24 different endpoints, or
Actions, available for the NHTSA Vehicles API.
To see how these Actions are implemented you can visit the documentation for the NHTSA class, which is a class exported by this package that implements all of the individual Action wrapper class methods.
List of Actions
Offline VIN Validation
isValidVin is a method exported by this package that takes a single string argument, a Vehicle Identification Number, and performs an offline VIN validation. It will return true if the VIN passes the algorithm, otherwise false.
This can be useful if you want to ensure a valid VIN is entered by the user, which will prevent unnecessary HTTP/API requests. See the isValidVin module for more information.