PVAW: Python Vehicle API Wrapper

A Python wrapper for the National Highway Traffic Saftey Association (NHTSA) Vehicle API

License

Documentation

Istalling PVAW

pip install pvaw

Importing PVAW

import pvaw as pv

Vin Decoding

The NHTSA Vehicle API supports individual and batch decoding.

Vin Class

class pvaw.Vin(full_or_partial_vin, model_year=None)

Parameters:

full_or_partial_vin: string representing a Vehicle Identification Number (VIN). It can be either the full VIN (e.g. "3C6JR7AT4EG248404"), or be a subset of the VIN with missing characters replaced by the '*' character (e.g. "5YJSA3DS*EF")

model_year: string or integer representing the model year of the vehicle. Defaults to None.

Constructing a Vin

# creating a Vin object from partial vin
vin_1 = pv.Vin("5YJSA3DS*EF")

# creationg a Vin object from partial vin and year
vin_2 = pv.Vin("5UXWX7C5*BA", 2011)

Decoding a Vin

pvaw.Vin.decode()

Returns: A Vehicle object with information about the Vin's associated vehicle

vehicle = vin_1.decode()
vehicle

Getting Key Attributes

print(vehicle.model_year)
print(vehicle.make)
print(vehicle.manufacturer)
print(vehicle.model)
print(vehicle.full_or_partial_vin)
print(vehicle.vehicle_type)

2014
TESLA
TESLA, INC.
Model S
5YJSA3DS*EF
PASSENGER CAR

Getting JSON Results

vehicle.get_results()

{'ABS': '',
 'ActiveSafetySysNote': '',
 'AdaptiveCruiseControl': '',
 'AdaptiveDrivingBeam': '',
 'AdaptiveHeadlights': '',
 'AdditionalErrorText': 'The error positions are indicated by ! in Suggested VIN. In the Possible values section, each pair of parenthesis indicate information about each error position in VIN . The Numeric value before the : indicates the position in error and the values after the : indicate the possible values that are allowed in this position Unused position(s): 8;',
 'AirBagLocCurtain': '',
 'AirBagLocFront': '1st Row (Driver & Passenger)',
 ...

Getting DataFrame

# Getting key attribute df dropping nan
vehicle.get_df()

# Getting full raw data df not dropping nan
vehicle.get_df(raw=True, drop_na=False)

Batch Decoding

pvaw.decode_vins(vins)

Parameters: vins: list of Vin objects

Returns: ResultsList object which stores a list of Vehicle objects

vehicles = pv.decode_vins([vin_1, vin_2])
vehicles

Accessing each Vehicle

# Iterating through vehicles
for vehicle in vehicles:
    display(vehicle)

# Indexing Vehicles
first = vehicles[0]
last = vehicles[len(vehicles) - 1]

Getting JSON Results

vehicles.get_results()

[{'ABS': '',
  'ActiveSafetySysNote': '',
  'AdaptiveCruiseControl': '',
  'AdaptiveDrivingBeam': '',
  'AdaptiveHeadlights': '',
  'AdditionalErrorText': 'The error positions are indicated by ! in Suggested VIN. In the Possible values section, each pair of parenthesis indicate information about each error position in VIN . The Numeric value before the : indicates the position in error and the values after the : indicate the possible values that are allowed in this position Unused position(s): 8;',
  'AirBagLocCurtain': '',
  'AirBagLocFront': '1st Row (Driver & Passenger)',
  'AirBagLocKnee': '1st Row (Driver & Passenger)',
  'AirBagLocSeatCushion': '',
  ...

Getting DataFrame

# Getting key attribute df dropping nan
vehicles.get_df()

# Getting full raw data df not dropping nan
vehicles.get_df(raw=True, drop_na=False)

WMI Methods

The NHTSA Vehicle API supports wmi decoding

WMI Decoding

pvaw.decode_wmi(wmi)

Parameters: wmi: str of length 3 representing VIN position 1-3 (e.g. "1FD") or 6 representing VIN positions 1-3 & 12-14 (e.g. "1G9340")

Returns: WMIInfo object with information on wmi

wmi_info = pv.decode_wmi("JTL")
wmi_info

Getting Key Attributes

print(wmi_info.wmi)
print(wmi_info.manufacturer)
print(wmi_info.vehicle_type)

JTL
TOYOTA MOTOR NORTH AMERICA, INC
Multipurpose Passenger Vehicle (MPV)

Getting JSON Results

wmi_info.get_results()

{'CommonName': 'Toyota',
 'CreatedOn': '2015-05-04',
 'DateAvailableToPublic': '2015-01-01',
 'Make': 'TOYOTA',
 'ManufacturerName': 'TOYOTA MOTOR NORTH AMERICA, INC',
 'ParentCompanyName': 'TOYOTA MOTOR CORPORATION',
 'URL': 'http://www.toyota.com',
 'UpdatedOn': None,
 'VehicleType': 'Multipurpose Passenger Vehicle (MPV)',
 'WMI': 'JTL'}

Getting DataFrame

# Getting key attribute df dropping nan
wmi_info.get_df()

# Getting full raw data df not dropping nan
wmi_info.get_df(raw=True, drop_na=False)

Finding WMIs by Manufacturer

pvaw.get_wmis(manufacturer_search)

Parameters: manufacturer_search: a str representing part or all of the name of a Manufacturer (e.g. "Honda")

Returns: ResultsList object which stores a list of WMIInfo objects

wmi_infos = pv.get_wmis("Tesla")
wmi_infos

Accessing Each WMI

# Iterating through vehicles
for wmi_info in wmi_infos:
    display(wmi_info)

# Indexing Vehicles
first = wmi_infos[0]
last = wmi_infos[len(vehicles) - 1]

# Getting Key Attributes
print(first.wmi)
print(first.manufacturer)
print(first.vehicle_type)

5YJ
TESLA, INC.
Passenger Car

Getting JSON Results

wmi_infos.get_results()

[{'Country': 'UNITED STATES (USA)',
  'CreatedOn': '2015-03-04',
  'DateAvailableToPublic': '2015-01-01',
  'Id': 955,
  'Name': 'TESLA, INC.',
  'UpdatedOn': None,
  'VehicleType': 'Passenger Car',
  'WMI': '5YJ'},
 {'Country': 'UNITED STATES (USA)',
  'CreatedOn': '2015-04-16',
  'DateAvailableToPublic': '2015-01-01',
  'Id': 955,
  'Name': 'TESLA, INC.',
  'UpdatedOn': None,
  'VehicleType': 'Passenger Car',
  'WMI': 'SFZ'}]

Getting DataFrame

# Getting key attribute df dropping nan
wmi_infos.get_df()

# Getting full raw data df not dropping nan
wmi_infos.get_df(raw=True, drop_na=False)

Make Methods

pvaw.get_makes(manufacturer_name_or_id=None, model_year=None, vehicle_type=None)

Finding Makes by Manufacturer and Year or Vehicle Type

Parameters: manufacturer_name_or_id: a str representing part or all of the name of a manufacturer (e.g. "Honda") or an integer representing the manufacturer ID

model_year: a str or int representing the year makes must exist in (e.g. 2005)

vehicle_type: a str representing the type of vehicle that a make produces (e.g. "car")

NOTE: For this method, you can filter either by manufacturer_name_or_id or by vehicle_type, you cannot filter by both. Additionally, model_year can be passed in with manufacturer_name_or_id, but not with vehicle_type.

Returns: ResultsList object which stores a list of Make objects

# getting makes for manufacturer name search
makes = pv.get_makes("hyundai")

# getting makes for manufacturer name search and model year
makes_2 = pv.get_makes("tesla", 2020)

# getting makes for manufacturer ID and model year
makes_3 = pv.get_makes(988, 2005)

# getting makes by vehicle_type search
makes_4 = pv.get_makes(vehicle_type="car")

# displaying makes
makes_3

Accessing Each Make

# Iterating through makes
for m in makes_3:
    display(m)

# Indexing makes
first = makes_3[0]
last = makes_3[len(makes_3) - 1]

# Getting Key Attributes
print(first.make_id)
print(first.make_name)
print(first.manufacturer)
print(first.vehicle_type)

474
HONDA
HONDA OF AMERICA MFG., INC.
None

Getting JSON Results

makes_3.get_results()

[{'MakeId': 474,
  'MakeName': 'HONDA',
  'MfrId': 988,
  'MfrName': 'HONDA OF AMERICA MFG., INC.'},
 {'MakeId': 475,
  'MakeName': 'ACURA',
  'MfrId': 988,
  'MfrName': 'HONDA OF AMERICA MFG., INC.'}]

Getting DataFrame

# Getting key attribute df dropping nan
makes_3.get_df()

# Getting full raw data df not dropping nan
makes_3.get_df(raw=True, drop_na=False)

Manufacturer Methods

Getting Manufacturers

pvaw.get_manufacturers(m_type=None, page=1)

Parameters: m_type: a str representing part or all of the manufacturer type (e.g. "Intermediate")

page: int representing the api page number. Each page returns 100 manufacturers

Returns: ResultsList object which stores a list of Manufacturer objects

# getting manufacturers by api page number
manufacturers = pv.get_manufacturers(page=5)

# getting manufacturers by manufacturer type
manufacturers_2 = pv.get_manufacturers(m_type="complete", page=1)

Searching for Specific Manufacturers

pvaw.get_manufacturer_details(manufacturer_name_or_id)

Parameters: manufacturer_name_or_id: a str representing manufacturer name or an int representing the manufacturer ID

Returns: ResultsList object which stores a list of Manufacturer objects matching the manufacturer search

# getting manufacturer(s) from manufacturer name search
manufacturers_3 = pv.get_manufacturer_details("Toyota")

# getting manufacturer from manufacturter id
manufacturers_4 = pv.get_manufacturer_details(988)

Accessing Each Manufacturer

# Iterating through manufacturers
for m in manufacturers[:4]:
    display(m)

# Indexing manufacturers
first = manufacturers[0]
last = manufacturers[len(manufacturers) - 1]

# Getting Key Attributes
print(first.id)
print(first.common_name)
print(first.name)
print(first.vehicle_types)

1387
None
WOOPYONG MOTOR WHEEL LTD
[]

Getting JSON Results

manufacturers.get_results()

[{'Country': '',
  'Mfr_CommonName': None,
  'Mfr_ID': 1387,
  'Mfr_Name': 'WOOPYONG MOTOR WHEEL LTD',
  'VehicleTypes': []},
 {'Country': 'UNITED STATES (USA)',
  'Mfr_CommonName': None,
  'Mfr_ID': 1388,
  'Mfr_Name': 'WORCESTER TANK & EQUIPMENT CO., INC',
  'VehicleTypes': []},
 ...

Getting DataFrame

# Getting key attribute df dropping nan
manufacturers.get_df()

# Getting full raw data df not dropping nan
manufacturers.get_df(raw=True, drop_na=False)