DOCSEARCHbyAlgolia
Submit Docs

@shaggytools/nhtsa-api-wrapper

website·Indexed 33 days ago

https://vpic.shaggytech.com/

A thin JavaScript and TypeScript client for the NHTSA VPIC API. Version 3.0.4 provides helper functions for decoding VINs, retrieving vehicle specifications, and fetching manufacturer, make, and model data. Includes utility functions like isValidVin and the useNHTSA composable for managing API requests and cached URLs.

Tokens
43.8K
Snippets
227
Records
277
Agent score
47%

What's inside nhtsa-api-wrapper

  1. Overview of @shaggytools/nhtsa-api-wrapper

    @shaggytools/nhtsa-api-wrapper is a thin JavaScript client for the NHTSA VPIC API, which is used to decode Vehicle Identification Numbers (VIN) and retrieve vehicle data (makes, models, years) for the US and Canada. The package provides 24 helper functions corresponding to the 24 VPIC API endpoints, removing the need to manually manage URL structures, query parameters, or data formatting. It is free to use as the underlying NHTSA API requires no API key.

  2. Overview of the useNHTSA composable function

    The useNHTSA composable returns an object containing helper functions for interacting with the NHTSA VPIC API. It provides methods for building API URLs, managing a cached URL in an internal state, and performing HTTP GET and POST requests.

    Each call to useNHTSA() creates a new instance with its own isolated internal state, allowing multiple independent URL caches to exist simultaneously. The get and post methods use the native fetch API and require Node.js version 18+ or a modern browser.

    import { useNHTSA } from '@shaggytools/nhtsa-api-wrapper'

const { get, post, createCachedUrl, createUrl, getCachedUrl } = useNHTSA()

  3. Decode a World Manufacturer Identifier (WMI)

    The DecodeWMI function retrieves information about the manufacturer associated with a specific WMI code. The WMI parameter can be either 3 characters (VIN positions 1-3) or 6 characters (VIN positions 1-3 and 12-14). Examples include 'JTD' or '1T9131'.
    import { DecodeWMI } from '@shaggytools/nhtsa-api-wrapper'

// Decode using a 3-character WMI
const response = await DecodeWMI('WVW')

  4. Decode a VIN using the VPIC API

    The VPIC API allows you to decode a Vehicle Identification Number (VIN) and receive the decoded vehicle data in JSON format. The API handles the processing internally, removing the need for the user to manage complex query strings, path parameters, or manual parsing.

  5. Decode WMI information using the DecodeWMI function

    The DecodeWMI function retrieves information about the World Manufacturer Identifier (WMI) for a specific code. The WMI parameter can be provided as either 3 characters (VIN positions 1-3) or 6 characters (VIN positions 1-3 and 12-14). Examples include "JTD" or "1T9131".
    import { DecodeWMI } from '@shaggytools/nhtsa-api-wrapper';

// Fetch WMI data
const response = await DecodeWMI('JTD');

// Return only the API URL instead of fetching data
const url = await DecodeWMI('1T9131', false);

  6. Retrieve manufacturer details using GetManufacturerDetails

    The GetManufacturerDetails function retrieves detailed information about a specific vehicle manufacturer. It supports searching by either a manufacturer's unique ID or their name.

    • Search by ID: If a number is provided, the function performs an exact match on the Manufacturer's ID.
    • Search by Name: If a string is provided, the function performs a partial match (LIKE) on the manufacturer's name (e.g., "tesla" or "HONDA OF CANADA MFG., INC.").

    By default, the function fetches the data from the VPIC API. If doFetch is set to false, it returns the API URL instead of the data.

    import { GetManufacturerDetails } from '@shaggytools/nhtsa-api-wrapper'

// Search by name (partial match)
const responseByName = await GetManufacturerDetails('tesla');

// Search by ID (exact match)
const responseById = await GetManufacturerDetails(955);

  7. Understand the NHTSA API response structure

    The NhtsaResponse<T> type is a generic wrapper for all data returned from the NHTSA VPIC API. It provides metadata about the request and a typed array of results.
    interface NhtsaResponse<T> {
  Count: number;         // Number of items returned; 0 if no results
  Message: string;       // Description of results or error info if Count is 0
  Results: T[];          // Array of objects specific to the API action
  SearchCriteria: string | null; // The search terms (VIN, WMI, etc.) used in the request
}

  8. Understand the VPIC API response structure

    The VPIC API returns a JSON object (via the NhtsaResponse<T> type) containing metadata about the request and an array of results. The specific type of the Results array depends on the endpoint used (typically the endpoint name with 'Results' appended).

    Key properties include:

    • Count: A number representing the number of results or keys returned. If 0, the Results array is empty.
    • Message: A string indicating success or providing error details (e.g., 'ERROR: Invalid Year Submitted').
    • Results: An array of objects containing the actual data.
    • SearchCriteria: A string reflecting the input used for the search (e.g., 'VIN:WA1A4AFY2J2008189').
    type NhtsaResponse<T> = {
  Count: number
  Message: string
  Results: Array<T>
  SearchCriteria: string | null
}

// Example for the DecodeVin endpoint
type DecodeVinResults = {
  Variable: string
  Value: string
  ValueId: number
  VariableId: number
}

  9. Retrieve vehicle models for a specific make using GetModelsForMake

    GetModelsForMake retrieves a list of vehicle models from the vPIC dataset for a specified make. The makeName parameter supports partial or full names (e.g., "Harley" or "Harley Davidson").

    By default, the function fetches the data. If doFetch is set to false, the function returns the API URL instead of the data, allowing the developer to handle the network request manually.

    import { GetModelsForMake } from '@shaggytools/nhtsa-api-wrapper'

// Fetch data directly
const response = await GetModelsForMake('audi');

// Get the URL to fetch data manually
const url = await GetModelsForMake('audi', false);

  10. Decode a VIN using DecodeVinValues

    The DecodeVinValues function decodes a Vehicle Identification Number (VIN) and returns vehicle information in a flat format. Unlike nested format endpoints, this returns an array containing a single object where each key is a variable name and the value is the corresponding vehicle attribute. It supports full VINs and partial VINs (less than 17 characters), where a * can be used for unavailable characters.
    // Example: Decode a full VIN
const response = await DecodeVinValues('WA1A4AFY2J2008189');

// Example: Decode a partial VIN
const partialResponse = await DecodeVinValues('5UXWX7C5*BA');

  11. Retrieve vehicle models using GetModelsForMakeYear

    GetModelsForMakeYear returns a list of models from the vPIC dataset for a specified make and either a model year, a vehicle type, or both.

    Requirements:

    • params.make is always required (supports partial or full names).
    • At least one of params.modelYear (years $\ge$ 1995) or params.vehicleType must be provided.

    By default, the function fetches the data. If doFetch is set to false, it returns the constructed API URL string instead of the data.

    import { GetModelsForMakeYear } from '@shaggytools/nhtsa-api-wrapper'

// Example: Get models for a specific make and year
const response = await GetModelsForMakeYear({
  make: 'Audi',
  modelYear: 2018,
});

  12. Retrieve vehicle types for a specific Make ID using GetVehicleTypesForMakeId

    The GetVehicleTypesForMakeId function retrieves the vehicle models/types associated with a specific Make ID from the vPIC dataset.

    How to obtain a Make ID

    Make IDs can be sourced from other API endpoints:

    • GetAllMakes, GetMakeForManufacturer, GetModelsForMake, or GetModelsForMakeYear (via the MAKE_ID key).
    • DecodeVinValues or DecodeVinValuesBatch (via the MakeID key).
    • DecodeVin or DecodeVinExtended (via the ValueId key in the result object where Variable is "Make" and VariableId is 26).
    import { GetVehicleTypesForMakeId } from '@shaggytools/nhtsa-api-wrapper'

// Fetch vehicle types for Make ID 449
const response = await GetVehicleTypesForMakeId(449)