Important: This documentation applies to v2 of this package.
For v3 docs see vpic.shaggytech.com
API Documentation

Class

NHTSA

api/NHTSA~NHTSA(userConfigopt)

Constructor

# new NHTSA(userConfigopt)

Parameters:
Name Type Attributes Description
userConfig FetchConfig <optional>

Configuration options to construct the class with.
Implements:

View Source api/NHTSA.ts, line 14

Examples

Node bundle

const { NHTSA } = require('@shaggytools/nhtsa-api-wrapper');

const Wrapper = new NHTSA();

// Decode a VIN and return a response of type ApiResponse
const response = Wrapper.DecodeVinValues('3VWD07AJ5EM388202').catch(error => error)

// or get details about a specific manufacturer, plus 23 other available Actions.
const hondaDetails = Wrapper.GetManufacturerDetails('Honda').catch(error => error)

Browser bundle

  // Change <version> to specific version number "x.x.xx",
  // or remove <version> completely for the most recently published version
  <script
    type="text/javascript"
    src="https://cdn.jsdelivr.net/npm/@shaggytools/nhtsa-api-wrapper/<version>/dist/bundle.min.js"
  ></script>

<script type="text/javascript">
// NHSTA is the global browser window exported by this package
const Decoder = new NHSTA.NHSTA();

const result = await Decoder.DecodeVin('3VWD07AJ5EM388202')
  .catch(err => err);
</script>

Module - Node lazy loading

const { NHTSA } = await import('@shaggytools/nhtsa-api-wrapper/dist/module/index.js')
  .catch(err => err);

const ApiClient = new NHTSA();

const results = await ApiClient.DecodeVin('3VWD07AJ5EM388202')
  .catch(err => err)

Module - Browser lazy loading

<script type="module">
  const { NHSTA } = await import('https://unpkg.com/@shaggytools/nhtsa-api-wrapper/dist/module/index.js')
   .catch(err => err);

  const ApiClient = new NHSTA();

  const { Results } = await ApiClient.DecodeVin('3VWD07AJ5EM388202')
   .catch(err => err)

  console.log(Results)
</script>

Extends

Methods

# async buildQueryString(params, allowEmptyStringValuesopt) → {Promise.<string>}

Builds a query string from QueryStringParameters.

Parameters:
Name Type Attributes Default Description
params QueryStringParameters

Object containing Key:Value pairs to build the URL query string with.
allowEmptyStringValues boolean <optional>
 false

Set to true to add empty parameter values to the returned query string.

  • Given params of {paramName: ""} , setting this to true will use 'paramName=' in the final query string.
  • GetCanadianVehicleSpecifications is the only API Action that requires this functionality.
Inherited From:

View Source api/Fetch.ts, line 86

A formatted NHSTA.dot.gov Vehicles API query string.

Promise.<string>

# async DecodeVin(vin, paramsopt) → {Promise.<DecodeVinResponse>}

The DecodeVin API Action will decode the VIN and the decoded output will be made available in the format of Key-value pairs.

  • Providing params.modelYear allows for the decoding to specifically be done in the current, or older (pre-1980), model year ranges.
    • It is recommended to always provide params.modelYear if the model year is known at the time of decoding.
  • This API also supports partial VIN decoding (VINs that are less than 17 characters).
    • In this case, the VIN will be decoded partially with the available characters.
    • In case of partial VINs, a "*" could be used to indicate the unavailable characters.
    • The 9th digit is not necessary.
Parameters:
Name Type Attributes Default Description
vin string

Vehicle Identification Number (full or partial).
params object <optional>
 {}

Query Search Parameters to append to the URL.
modelYear number <optional>

Optional Model Year search parameter.
Implements:

View Source api/actions/DecodeVin.ts, line 47

  • Api Response object.
Promise.<DecodeVinResponse>

# async DecodeVinExtended(vin, paramsopt) → {Promise.<DecodeVinExtendedResponse>}

This is exactly like the DecodeVin method but provides additional information on variables related to other NHTSA programs like NCSA, etc.

  • This will decode the VIN and the decoded output will be made available in the format of Key-value pairs.
  • In the returned 'Results` object:
    • The IDs (VariableID and ValueID) represent the unique ID associated with the Variable/Value.
    • In case of text variables, the ValueID is not applicable.
  • Providing params.modelYear allows for the decoding to specifically be done in the current, or older (pre-1980), model year ranges.
    • It is recommended to always provide params.modelYear if the model year is known at the time of decoding.
  • This Action also supports partial VIN decoding (VINs that are less than 17 characters).
    • In this case, the VIN will be decoded partially with the available characters.
    • In case of partial VINs, a "*" could be used to indicate the unavailable characters.
    • The 9th digit is not necessary.
Parameters:
Name Type Attributes Default Description
vin string

Vehicle Identification Number (full or partial).
params object <optional>
 {}

Query Search Parameters to append to the URL.
modelYear string | number <optional>

Optional Model Year search parameter.
Implements:

View Source api/actions/DecodeVinExtended.ts, line 54

  • Api Response object.
Promise.<DecodeVinExtendedResponse>

# async DecodeVinValues(vin, paramsopt) → {Promise.<DecodeVinValuesResponse>}

The DecodeVinValues API Action will decode the VIN with the Results returned in a flat file format.

  • The Results will be made available in a flat file format of a single object containing 'key: value' results.
  • Providing params.modelYear allows for the decoding to specifically be done in the current, or older (pre-1980), model year ranges.
    • It is recommended to always provide params.modelYear if the model year is known at the time of decoding.
  • This Action also supports partial VIN decoding (VINs that are less than 17 characters).
    • In this case, the VIN will be decoded partially with the available characters.
    • In case of partial VINs, a "*" could be used to indicate the unavailable characters.
Parameters:
Name Type Attributes Default Description
vin string

Vehicle Identification Number (full or partial).
params object <optional>
 {}

Query Search Parameters to append to the URL.
modelYear string | number <optional>

Optional Model Year search parameter.
Implements:

View Source api/actions/DecodeVinValues.ts, line 48

Api Response object.

Promise.<DecodeVinValuesResponse>

# async DecodeVinValuesExtended(vin, paramsopt) → {Promise.<DecodeVinValuesExtendedResponse>}

This is exactly like the DecodeVinValues (flat format Results) method but provides additional information on variables related to other NHTSA programs like NCSA, etc.

  • The Results will be made available in a flat file format of a single object containing 'key: value' results.
  • Providing params.modelYear allows for the decoding to specifically be done in the current, or older (pre-1980), model year ranges.
    • It is recommended to always provide params.modelYear if the model year is known at the time of decoding.
  • This Action also supports partial VIN decoding (VINs that are less than 17 characters).
    • In this case, the VIN will be decoded partially with the available characters.
    • In case of partial VINs, a "*" could be used to indicate the unavailable characters.
Parameters:
Name Type Attributes Default Description
vin string

Vehicle Identification Number (full or partial).
params object <optional>
 {}

Query Search Parameters to append to the URL.
modelYear string | number <optional>

Optional Model Year search parameter.
Implements:

View Source api/actions/DecodeVinValuesExtended.ts, line 51

Api Response object.

Promise.<DecodeVinValuesExtendedResponse>

# async DecodeWMI(WMI) → {Promise.<DecodeWMIResults>}

This provides information on the World Manufacturer Identifier for a specific WMI code.

  • WMI may be put in as either 3 characters representing VIN position 1-3 or 6 characters representing VIN positions 1-3 & 12-14. Example "JTD", "1T9131".
Parameters:
Name Type Description
WMI string

World Manufacturer Identifier.
Implements:

View Source api/actions/DecodeWMI.ts, line 40

Api Response object.

Promise.<DecodeWMIResults>

# async get(url, optionsopt) → {Promise.<module:api/Fetch.ApiResponse>}

Uses the isomorphic-unfetch npm package to send HTTP requests and retrieve data from an API.

Parameters:
Name Type Attributes Description
url string

URL to fetch data from.
options FetchRequestOptions <optional>

Fetch options.
Inherited From:

View Source api/Fetch.ts, line 113

Response from the API.

Promise.<module:api/Fetch.ApiResponse>

# async GetAllMakes() → {Promise.<GetAllMakesResponse>}

This provides a list of all the Makes available in the vPIC Dataset.

Implements:

View Source api/actions/GetAllMakes.ts, line 35

Api Response object.

Promise.<GetAllMakesResponse>

# async GetAllManufacturers(paramsopt) → {Promise.<module:api.ApiResponse>}

This provides a list of all the Manufacturers available in vPIC Dataset.

  • params.manufacturerType allows the user to filter the list based on manufacturer type, ('Incomplete Vehicles', 'Completed Vehicle Manufacturer', 'Incomplete Vehicle Manufacturer', 'Intermediate Manufacturer', 'Final-Stage Manufacturer', 'Alterer', or any partial match of those strings).
  • You can get a list of all manufacturer types with the following API Action: GetVehicleVariableValuesList('manufacturer type')
  • Results are provided in pages of 100 items.
  • Provide a number value for params.page to specify 1st (default), 2nd, 3rd, Nth, etc page.
Parameters:
Name Type Attributes Default Description
params object <optional>
 {}

Query Search Parameters to append to the URL.
manufacturerType string <optional>

See method description.
page number <optional>

Specify the page number (results returned 100 at a time).
Implements:

View Source api/actions/GetAllManufacturers.ts, line 47

Api Response object.

Promise.<module:api.ApiResponse>

# async GetCanadianVehicleSpecifications(params) → {Promise.<GetCanadianVehicleSpecificationsResponse>}

The Canadian Vehicle Specifications (CVS) consists of a database of original vehicle dimensions, used primarily in collision investigation and reconstruction, combined with a search engine.

The database is compiled annually by the Collision Investigation and Research Division of Transport Canada. Visit official Canadian Vehicle Specifications page for more details.

This API action will return a 404 html error if any of the query parameters in params are missing from the query string. This is the only API action with this behaviour. Therefore, parameters are inserted into the query string as empty strings if not provided by the user.

Parameters:
Name Type Attributes Description
params object

Query Search Parameters to append to the URL.
year number

Model year of the vehicle (required) - Number, >= 1971.
make string <optional>

Vehicle's make, like "Honda", "Toyota", etc...
model string <optional>

Vehicle's model, like "Pilot", "Focus". Can also include some other elements like Body Type, Engine Model/size, etc...
units string <optional>

"Metric" (default), or "US" for United States customary units.
Implements:

View Source api/actions/GetCanadianVehicleSpecifications.ts, line 51

Api Response object.

Promise.<GetCanadianVehicleSpecificationsResponse>

# async GetEquipmentPlantCodes(params) → {Promise.<GetEquipmentPlantCodesResponse>}

Returns assigned Equipment Plant Codes. Can be filtered by Year, Equipment Type and Report Type.

params.year:

  • Only years >= 2016 are supported

params.equipmentType:

  • 1 (Tires)
  • 3 (Brake Hoses)
  • 13 (Glazing)
  • 16 (Retread)

params.reportType:

  • 'New' (The Equipment Plant Code was assigned during the selected year).
  • 'Updated' (The Equipment Plant data was modified during the selected year).
  • 'Closed' (The Equipment Plant is no longer Active).
  • 'All' (All Equipment Plant Codes regardless of year, including their status (active or closed)).
Parameters:
Name Type Description
params object

Query Search Parameters to append to the URL.
year number

Model year of the vehicle - Number, >= 2016.
equipmentType number

Number equal to 1, 3, 13, or 16.
reportType string

'New', 'Updated', 'Closed', or 'All'.
Implements:

View Source api/actions/GetEquipmentPlantCodes.ts, line 56

Api Response object.

Promise.<GetEquipmentPlantCodesResponse>

# async GetMakeForManufacturer(manufacturer) → {Promise.<GetMakeForManufacturer>}

This returns all the Makes in the vPIC dataset for a specified manufacturer that is requested.

  • If supplied manufacturer is a number - method will do exact match on Manufacturer's Id.
  • If supplied manufacturer is a string - it will look for manufacturers whose name is LIKE the provided name (it accepts a partial manufacturer name as an input).
  • manufacturer name can be a partial name, or a full name for more specificity (e.g., "988", "HONDA", "HONDA OF CANADA MFG., INC.", etc.).
  • Multiple results are returned in case of multiple matches.
Parameters:
Name Type Description
manufacturer string | number

Manufacturer Name (string) or Manufacturer ID (number).
Implements:

View Source api/actions/GetMakeForManufacturer.ts, line 44

Api Response object.

Promise.<GetMakeForManufacturer>

# async GetMakesForManufacturerAndYear(manufacturer, params) → {Promise.<GetMakesForManufacturerAndYearResponse>}

This returns all the Makes in the vPIC dataset for a specified manufacturer, and whose Year From and Year To range cover the specified year.

  • If supplied manufacturer is a number - method will do exact match on Manufacturer's Id.
  • If supplied manufacturer is a string - it will look for manufacturers whose name is LIKE the provided name (it accepts a partial manufacturer name as an input).
  • Multiple results are returned in case of multiple matches.
  • Manufacturer can be idenfitied by Id, a partial name, or a full name (e.g., "988", "HONDA", "HONDA OF CANADA MFG., INC.", etc.).
Parameters:
Name Type Description
manufacturer string | number

Manufacturer Name (string) or Manufacturer ID (number).
params object

Query Search Parameters to append to the URL.
year number

Model year of the vehicle - Number, >= 2016.
Implements:

View Source api/actions/GetMakesForManufacturerAndYear.ts, line 48

Api Response object.

Promise.<GetMakesForManufacturerAndYearResponse>

# async GetMakesForVehicleType(typeName) → {Promise.<GetMakesForVehicleTypeResponse>}

This returns all the Makes in the vPIC dataset for a specified vehicle type (typeName), whose name is LIKE the vehicle type name in vPIC Dataset.

  • Vehicle typeName can be a partial name, or a full name for more specificity (e.g., "Vehicle", "Moto", "Low Speed Vehicle", etc.).
Parameters:
Name Type Description
typeName string

A partial or full vehicle type name.
Implements:

View Source api/actions/GetMakesForVehicleType.ts, line 41

Api Response object.

Promise.<GetMakesForVehicleTypeResponse>

# async GetManufacturerDetails(manufacturer) → {Promise.<GetManufacturerDetailsResponse>}

This provides the details for a specific manufacturer that is requested.

  • If supplied manufacturer is a number - method will do exact match on Manufacturer's Id.
  • If supplied manufacturer is a string - it will look for manufacturers whose name is LIKE the provided name, (it accepts a partial manufacturer name as an input).
  • Multiple results are returned in case of multiple matches.
Parameters:
Name Type Description
manufacturer string | number

Manufacturer Name (string) or Manufacturer ID (number).
Implements:

View Source api/actions/GetManufacturerDetails.ts, line 42

Api Response object.

Promise.<GetManufacturerDetailsResponse>

# async GetModelsForMake(makeName) → {Promise.<GetModelsForMakeResponse>}

This returns the Models in the vPIC dataset for a specified makeName whose Name is LIKE the Make in vPIC Dataset.

  • makeName can be a partial, or a full for more specificity (e.g., "Harley", "Harley Davidson", etc.).
Parameters:
Name Type Description
makeName string

Vehicle make name.
Implements:

View Source api/actions/GetModelsForMake.ts, line 41

Api Response object.

Promise.<GetModelsForMakeResponse>

# async GetModelsForMakeId(makeID) → {Promise.<GetModelsForMakeIdResponse>}

This returns the Models in the vPIC dataset for a specified Make whose Id is equal to the makeId in the vPIC Dataset.

Parameters:
Name Type Description
makeID number

Vehicle make ID (number).
Implements:

View Source api/actions/GetModelsForMakeId.ts, line 39

Api Response object.

Promise.<GetModelsForMakeIdResponse>

# async GetModelsForMakeIdYear(params) → {Promise.<GetModelsForMakeIdYearResponse>}

This returns the Models in the vPIC dataset for a specified Model Year and Make whose name is LIKE the Make in the vPIC Dataset.

  • params.makeId is a number and is a required query parameter.

A minimum of one of the following are required (or a combination of both):

  • params.modelYear is a number (greater than 1995)
  • params.vehicleType can be a partial name, or a full name for more specificity (e.g., "Vehicle", "Moto", "Low Speed Vehicle", etc.).
Parameters:
Name Type Attributes Description
params object

Query Search Parameters to append to the URL.
makeId number

Make ID to search.
modelYear number <optional>

A number representing the model year to search (greater than 1995).
vehicleType string <optional>

String representing the vehicle type to search.
Implements:

View Source api/actions/GetModelsForMakeIdYear.ts, line 48

Api Response object.

Promise.<GetModelsForMakeIdYearResponse>

# async GetModelsForMakeYear(params) → {Promise.<GetModelsForMakeYearResponse>}

This returns the Models in the vPIC dataset for a specified Model Year and Make whose name is LIKE the Make in the vPIC Dataset.

  • params.make is required. It can be a partial, or a full name for more specificity (e.g., "Harley", "Harley Davidson", etc.).

A minimum of one of the following are required (or a combination of both):

  • params.modelYear is a number (greater than 1995)
  • params.vehicleType can be a partial name, or a full name for more specificity (e.g., "Vehicle", "Moto", "Low Speed Vehicle", etc.).
Parameters:
Name Type Attributes Description
params object

Query Search Parameters to append to the URL.
make string

Make name to search.
modelYear number <optional>

A number representing the model year to search (greater than 1995).
vehicleType string <optional>

String representing the vehicle type to search.
Implements:

View Source api/actions/GetModelsForMakeYear.ts, line 51

Api Response object.

Promise.<GetModelsForMakeYearResponse>

# async GetParts(paramsopt) → {Promise.<GetPartsResponse>}

This provides a list of ORGs with letter date in the given range of the dates and with specified Type (params.type) of ORG.

  • Up to 1000 results will be returned at a time.
  • Get the next page by incrementing the params.page query parameter.
  • All query params are optional.
Parameters:
Name Type Attributes Description
params object <optional>

Query Search Parameters to append to the URL.
type number <optional>

Specified type of ORG to search.
fromDate string <optional>

Start date of search query.
toDate string <optional>

End date of search query.
page number <optional>

Which page number of results to request (100 results per page).
Implements:

View Source api/actions/GetParts.ts, line 46

Api Response object.

Promise.<GetPartsResponse>

# async GetVehicleTypesForMake(makeName) → {Promise.<GetVehicleTypesForMakeResponse>}

This returns all the Vehicle Types in the vPIC dataset for a specified Make, whose name is LIKE the make name in the vPIC Dataset.

  • makeName can be a partial name, or a full name for more specificity (e.g., "Merc", "Mercedes Benz", etc.).
Parameters:
Name Type Description
makeName string

Name of the vehicle make to search.
Implements:

View Source api/actions/GetVehicleTypesForMake.ts, line 41

Api Response object.

Promise.<GetVehicleTypesForMakeResponse>

# async GetVehicleTypesForMakeId(makeID) → {Promise.<GetVehicleTypesForMakeIdResponse>}

This returns all the Vehicle Types in the vPIC dataset for a specified Make and whose ID equals the make ID in the vPIC Dataset.

Parameters:
Name Type Description
makeID number

Vehicle make ID.
Implements:

View Source api/actions/GetVehicleTypesForMakeId.ts, line 39

Api Response object.

Promise.<GetVehicleTypesForMakeIdResponse>

# async GetVehicleVariableList() → {Promise.<GetVehicleVariableListResponse>}

This provides a list of all the Vehicle related variables that are in the vPIC dataset.

  • Information on the name, description and the type of the variable is provided.
Implements:

View Source api/actions/GetVehicleVariableList.ts, line 36

Api Response object.

Promise.<GetVehicleVariableListResponse>

# async GetVehicleVariableValuesList(variableValue) → {Promise.<GetVehicleVariableValuesListResponse>}

This provides a list of all the accepted values for a given variable that are stored in the vPIC dataset.

This applies to only "Look up" type of variables.

  • variableValue can either be a:
    • Variable Name ("battery type" in first example, please use full name, not just part of it),
    • or Variable ID (number).
Parameters:
Name Type Description
variableValue string | number

The variable you want to get a values list of.
Implements:

View Source api/actions/GetVehicleVariableValuesList.ts, line 43

Api Response object.

Promise.<GetVehicleVariableValuesListResponse>

# async GetWMIsForManufacturer(manufacturer, paramsopt) → {Promise.<GetWMIsForManufacturerResponse>}

Provides information on the World Manufacturer Identifier (WMI) for a specified manufacturer.

  • Only WMIs registered in vPICList are displayed.
  • manufacturer can be a partial name, or a full name for more specificity, or WMI ID number (e.g., "Merc", "Mercedes Benz", 987, etc.).
  • vehicleType can be a string or number (e.g., "car", 1)
Parameters:
Name Type Attributes Default Description
manufacturer string | number

Manufacturer Name.
params object <optional>
 {}

Query Search Parameters to append to the URL.
vehicleType string | number <optional>

Optional Vehicle Type search parameter.
Implements:

View Source api/actions/GetWMIsForManufacturer.ts, line 44

Api Response object.

Promise.<GetWMIsForManufacturerResponse>