@shaggytools/nhtsa-api-wrapper

Appearance

On this page

GetModelsForMakeYear ​

typescript
async function GetModelsForMakeYear(
  params: {
    make: string
  } & AtLeastOne<{
    modelYear?: string | number
    vehicleType?: string
  }>,
  doFetch?: boolean
): Promise<NhtsaResponse<GetModelsForMakeYearResults> | string>

💡 More In Depth

See: Package Reference

Description ​

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

❗ Required Parameters

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 also required (or a combination of both):

  • params.modelYear year you want to search for (years >= 1995 are supported according to NHTSA docs)
  • params.vehicleType can be a partial name, or a full name for more specificity, e.g., "Vehicle", "Moto", "Low Speed Vehicle", etc.

NOTE: This endpoint requires special behind the scenes handling of the params object, such that none of the params are used in the query string and are instead used as part of the URL path for the endpoint.

Parameters ​

NameTypeDefault ValueDescription
paramsObjectundefinedObject of query search names and values to append to the URL as a query string.
params.makestringundefinedMake name to search
params.modelYear?string | numberundefinedA number representing the model year to search (required if !vehicleType)
params.vehicleType?stringundefinedString representing the vehicle type to search (required if !modelYear)
doFetchbooleantrueWhether to fetch the data or just return the URL (default: true)

📝 NOTE

Any params that are not listed in the table above will be ignored.

Set doFetch to false if you want to fetch the data yourself.

Returns ​

Returns a Promise that resolves to a NhtsaResponse object containing an array of GetModelsForMakeYearResults objects in the Results key.

typescript
=> Promise<NhtsaResponse<GetModelsForMakeYearResults>>
typescript
type NhtsaApiResponse<GetModelsForMakeYearResults> = {
  Count: number
  Message: string
  Results: Array<GetModelsForMakeYearResults>
  SearchCriteria: string
}
🔍 Click to Show Full Example Response
ts
// Using GetModelsForMakeYear({ make: 'Audi', modelYear: 2018 })
const exampleResponse = {
  Count: 24,
  Message: 'Results returned successfully',
  Results: [
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 3145,
      Model_Name: 'TT',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 3146,
      Model_Name: 'A4',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 3147,
      Model_Name: 'S4',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 3148,
      Model_Name: 'A6',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 3151,
      Model_Name: 'A8',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 3676,
      Model_Name: 'A3',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 3677,
      Model_Name: 'S6',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 3678,
      Model_Name: 'S8',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 3679,
      Model_Name: 'Q7',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 3787,
      Model_Name: 'A5',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 3788,
      Model_Name: 'S5',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 3789,
      Model_Name: 'R8',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 3861,
      Model_Name: 'TTS',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 3862,
      Model_Name: 'Q5',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 4014,
      Model_Name: 'RS5',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 4015,
      Model_Name: 'A7',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 4016,
      Model_Name: 'TT RS',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 4051,
      Model_Name: 'Q3',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 4052,
      Model_Name: 'SQ5',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 8173,
      Model_Name: 'S3',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 8258,
      Model_Name: 'S7',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 8685,
      Model_Name: 'RS7',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 13759,
      Model_Name: 'A4 allroad',
    },
    {
      Make_ID: 582,
      Make_Name: 'AUDI',
      Model_ID: 16783,
      Model_Name: 'RS3',
    },
  ],
  SearchCriteria: 'Make:audi | ModelYear:2018',
}

If doFetch is set to false ​

Returns a URL string that can be used to fetch the data, does not fetch the data internally.

typescript
=> Promise<string>

// ex: => 'https://vpic.nhtsa.dot.gov/api/vehicles/GetModelsForMakeYear/make/audi/modelyear/2018/vehicleType/car?format=json'

💡 See: BYOF - Bring Your Own Fetch

Type - GetModelsForMakeYearResults ​

ts
type GetModelsForMakeYearResults = {
  Make_ID: number
  Make_Name: string
  Model_ID: number
  Model_Name: string
}

Ƭ GetModelsForMakeYearResults: Object

Objects returned in the Results array of GetModelsForMakeYear endpoint response.

Examples ​

Examples 1-3:

  • Fetches data from VPIC API

  • Returns:

typescript
=> Promise<NhtsaResponse<GetModelsForMakeYearResults>>

Example 1: Get Models for make and modelYear ​

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

const response = await GetModelsForMakeYear({
  make: 'Audi',
  modelYear: 2018,
})

Example 2: Get Models for make and vehicleType ​

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

const response = await GetModelsForMakeYear({
  make: 'audi',
  vehicleType: 'car',
})

Example 3: Get Models for make and modelYear and vehicleType ​

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

const response = await GetModelsForMakeYear({
  make: 'audi',
  modelYear: 2018,
  vehicleType: 'car',
})

Examples 4-6:

typescript
=> Promise<string>

Example 4: Get Models for make and modelYear and doFetch = false ​

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

const url = await GetModelsForMakeYear(
  {
    make: 'Audi',
    modelYear: 2018,
  },
  false
)

// url: 'https://vpic.nhtsa.dot.gov/api/vehicles/GetModelsForMakeYear/make/Audi/modelyear/2018?format=json'

Example 5: Get Models for make and vehicleType and doFetch = false ​

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

const url = await GetModelsForMakeYear(
  {
    make: 'Audi',
    vehicleType: 'car',
  },
  false
)

// url: 'https://vpic.nhtsa.dot.gov/api/vehicles/GetModelsForMakeYear/makeId/Audi/vehicleType/car?format=json'

Example 6: Get Models for make and modelYear and vehicleType and doFetch = false ​

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

const url = await GetModelsForMakeYear(
  {
    make: 'Audi',
    modelYear: 2018,
    vehicleType: 'car',
  },
  false
)

// url: 'https://vpic.nhtsa.dot.gov/api/vehicles/GetModelsForMakeYear/make/Audi/modelyear/2018/vehicleType/car?format=json'

Released under the MIT License.

Copyright © 2017-present Brandon Eichler