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
model_year | make | manufacturer | model | full_or_partial_vin | vehicle_type | |
---|---|---|---|---|---|---|
5YJSA3DS*EF | 2014 | TESLA | TESLA, INC. | Model S | 5YJSA3DS*EF | PASSENGER CAR |
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()
model_year | make | manufacturer | model | full_or_partial_vin | vehicle_type | |
---|---|---|---|---|---|---|
5YJSA3DS*EF | 2014 | TESLA | TESLA, INC. | Model S | 5YJSA3DS*EF | PASSENGER CAR |
# Getting full raw data df not dropping nan
vehicle.get_df(raw=True, drop_na=False)
ABS | ActiveSafetySysNote | AdaptiveCruiseControl | AdaptiveDrivingBeam | AdaptiveHeadlights | AdditionalErrorText | AirBagLocCurtain | AirBagLocFront | AirBagLocKnee | AirBagLocSeatCushion | ... | VIN | ValveTrainDesign | VehicleType | WheelBaseLong | WheelBaseShort | WheelBaseType | WheelSizeFront | WheelSizeRear | Wheels | Windows | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
5YJSA3DS*EF | NaN | NaN | NaN | NaN | NaN | The error positions are indicated by ! in Sugg... | NaN | 1st Row (Driver & Passenger) | 1st Row (Driver & Passenger) | NaN | ... | 5YJSA3DS*EF | NaN | PASSENGER CAR | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
1 rows × 145 columns
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
model_year | make | manufacturer | model | full_or_partial_vin | vehicle_type | |
---|---|---|---|---|---|---|
5YJSA3DS*EF | 2014 | TESLA | TESLA, INC. | Model S | 5YJSA3DS*EF | PASSENGER CAR |
5UXWX7C5*BA,2011 | 2011 | BMW | BMW MANUFACTURER CORPORATION / BMW NORTH AMERICA | X3 | 5UXWX7C5*BA | MULTIPURPOSE PASSENGER VEHICLE (MPV) |
Accessing each Vehicle
# Iterating through vehicles
for vehicle in vehicles:
display(vehicle)
# Indexing Vehicles
first = vehicles[0]
last = vehicles[len(vehicles) - 1]
model_year | make | manufacturer | model | full_or_partial_vin | vehicle_type | |
---|---|---|---|---|---|---|
5YJSA3DS*EF | 2014 | TESLA | TESLA, INC. | Model S | 5YJSA3DS*EF | PASSENGER CAR |
model_year | make | manufacturer | model | full_or_partial_vin | vehicle_type | |
---|---|---|---|---|---|---|
5UXWX7C5*BA,2011 | 2011 | BMW | BMW MANUFACTURER CORPORATION / BMW NORTH AMERICA | X3 | 5UXWX7C5*BA | MULTIPURPOSE PASSENGER VEHICLE (MPV) |
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()
model_year | make | manufacturer | model | full_or_partial_vin | vehicle_type | |
---|---|---|---|---|---|---|
5YJSA3DS*EF | 2014 | TESLA | TESLA, INC. | Model S | 5YJSA3DS*EF | PASSENGER CAR |
5UXWX7C5*BA,2011 | 2011 | BMW | BMW MANUFACTURER CORPORATION / BMW NORTH AMERICA | X3 | 5UXWX7C5*BA | MULTIPURPOSE PASSENGER VEHICLE (MPV) |
# Getting full raw data df not dropping nan
vehicles.get_df(raw=True, drop_na=False)
ABS | ActiveSafetySysNote | AdaptiveCruiseControl | AdaptiveDrivingBeam | AdaptiveHeadlights | AdditionalErrorText | AirBagLocCurtain | AirBagLocFront | AirBagLocKnee | AirBagLocSeatCushion | ... | VIN | ValveTrainDesign | VehicleType | WheelBaseLong | WheelBaseShort | WheelBaseType | WheelSizeFront | WheelSizeRear | Wheels | Windows | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
5YJSA3DS*EF | NaN | NaN | NaN | NaN | NaN | The error positions are indicated by ! in Sugg... | NaN | 1st Row (Driver & Passenger) | 1st Row (Driver & Passenger) | NaN | ... | 5YJSA3DS*EF | NaN | PASSENGER CAR | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
5UXWX7C5*BA,2011 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | 1st Row (Driver & Passenger) | NaN | NaN | ... | 5UXWX7C5*BA | NaN | MULTIPURPOSE PASSENGER VEHICLE (MPV) | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
2 rows × 145 columns
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
wmi | vehicle_type | manufacturer | |
---|---|---|---|
JTL | JTL | Multipurpose Passenger Vehicle (MPV) | TOYOTA MOTOR NORTH AMERICA, INC |
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()
wmi | vehicle_type | manufacturer | |
---|---|---|---|
JTL | JTL | Multipurpose Passenger Vehicle (MPV) | TOYOTA MOTOR NORTH AMERICA, INC |
# Getting full raw data df not dropping nan
wmi_info.get_df(raw=True, drop_na=False)
CommonName | CreatedOn | DateAvailableToPublic | Make | ManufacturerName | ParentCompanyName | URL | UpdatedOn | VehicleType | WMI | |
---|---|---|---|---|---|---|---|---|---|---|
JTL | Toyota | 2015-05-04 | 2015-01-01 | TOYOTA | TOYOTA MOTOR NORTH AMERICA, INC | TOYOTA MOTOR CORPORATION | http://www.toyota.com | None | Multipurpose Passenger Vehicle (MPV) | JTL |
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
wmi | vehicle_type | manufacturer | |
---|---|---|---|
5YJ | 5YJ | Passenger Car | TESLA, INC. |
SFZ | SFZ | Passenger Car | TESLA, INC. |
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)
wmi | vehicle_type | manufacturer | |
---|---|---|---|
5YJ | 5YJ | Passenger Car | TESLA, INC. |
wmi | vehicle_type | manufacturer | |
---|---|---|---|
SFZ | SFZ | Passenger Car | TESLA, INC. |
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()
wmi | vehicle_type | manufacturer | |
---|---|---|---|
5YJ | 5YJ | Passenger Car | TESLA, INC. |
SFZ | SFZ | Passenger Car | TESLA, INC. |
# Getting full raw data df not dropping nan
wmi_infos.get_df(raw=True, drop_na=False)
Country | CreatedOn | DateAvailableToPublic | Id | Name | UpdatedOn | VehicleType | WMI | |
---|---|---|---|---|---|---|---|---|
5YJ | UNITED STATES (USA) | 2015-03-04 | 2015-01-01 | 955 | TESLA, INC. | None | Passenger Car | 5YJ |
SFZ | UNITED STATES (USA) | 2015-04-16 | 2015-01-01 | 955 | TESLA, INC. | None | Passenger Car | SFZ |
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
make_id | make_name | manufacturer | |
---|---|---|---|
474-HONDA OF AMERICA MFG., INC. | 474 | HONDA | HONDA OF AMERICA MFG., INC. |
475-HONDA OF AMERICA MFG., INC. | 475 | ACURA | HONDA OF AMERICA MFG., INC. |
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)
make_id | make_name | manufacturer | |
---|---|---|---|
474-HONDA OF AMERICA MFG., INC. | 474 | HONDA | HONDA OF AMERICA MFG., INC. |
make_id | make_name | manufacturer | |
---|---|---|---|
475-HONDA OF AMERICA MFG., INC. | 475 | ACURA | HONDA OF AMERICA MFG., INC. |
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()
make_id | make_name | manufacturer | |
---|---|---|---|
474-HONDA OF AMERICA MFG., INC. | 474 | HONDA | HONDA OF AMERICA MFG., INC. |
475-HONDA OF AMERICA MFG., INC. | 475 | ACURA | HONDA OF AMERICA MFG., INC. |
# Getting full raw data df not dropping nan
makes_3.get_df(raw=True, drop_na=False)
MakeId | MakeName | MfrId | MfrName | |
---|---|---|---|---|
474-HONDA OF AMERICA MFG., INC. | 474 | HONDA | 988 | HONDA OF AMERICA MFG., INC. |
475-HONDA OF AMERICA MFG., INC. | 475 | ACURA | 988 | HONDA OF AMERICA MFG., INC. |
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)
name | vehicle_types | id | |
---|---|---|---|
1387 | WOOPYONG MOTOR WHEEL LTD | [] | 1387 |
name | vehicle_types | id | |
---|---|---|---|
1388 | WORCESTER TANK & EQUIPMENT CO., INC | [] | 1388 |
name | vehicle_types | id | |
---|---|---|---|
1389 | WORCESTER WHITE AUTOCAR, INC. | [] | 1389 |
name | vehicle_types | id | |
---|---|---|---|
1390 | WORKBENCH, INC. | [Trailer] | 1390 |
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()
name | vehicle_types | id | |
---|---|---|---|
1387 | WOOPYONG MOTOR WHEEL LTD | [] | 1387 |
1388 | WORCESTER TANK & EQUIPMENT CO., INC | [] | 1388 |
1389 | WORCESTER WHITE AUTOCAR, INC. | [] | 1389 |
1390 | WORKBENCH, INC. | [Trailer] | 1390 |
1391 | U-SCREEN U.S.A., INC. | [Trailer] | 1391 |
... | ... | ... | ... |
1479 | TAZZARI GL SPA | [Low Speed Vehicle (LSV)] | 1479 |
1480 | CHANGZHOU CITY WENMING VEHICLE ACCESSORIES FAC... | [] | 1480 |
1481 | SALSCO, INC. | [Trailer] | 1481 |
1482 | LIFT N LOCK, LLC | [] | 1482 |
1483 | CONTINENTAL BIOMASS INDUSTRIES, INC. | [] | 1483 |
92 rows × 3 columns
# Getting full raw data df not dropping nan
manufacturers.get_df(raw=True, drop_na=False)
Country | Mfr_CommonName | Mfr_ID | Mfr_Name | VehicleTypes | |
---|---|---|---|---|---|
1387 | NaN | None | 1387 | WOOPYONG MOTOR WHEEL LTD | [] |
1388 | UNITED STATES (USA) | None | 1388 | WORCESTER TANK & EQUIPMENT CO., INC | [] |
1389 | UNITED STATES (USA) | None | 1389 | WORCESTER WHITE AUTOCAR, INC. | [] |
1390 | UNITED STATES (USA) | None | 1390 | WORKBENCH, INC. | [{'IsPrimary': False, 'Name': 'Trailer'}] |
1391 | UNITED STATES (USA) | None | 1391 | U-SCREEN U.S.A., INC. | [{'IsPrimary': False, 'Name': 'Trailer'}] |
... | ... | ... | ... | ... | ... |
1479 | ITALY | None | 1479 | TAZZARI GL SPA | [{'IsPrimary': True, 'Name': 'Low Speed Vehicl... |
1480 | CHINA | None | 1480 | CHANGZHOU CITY WENMING VEHICLE ACCESSORIES FAC... | [] |
1481 | UNITED STATES (USA) | None | 1481 | SALSCO, INC. | [{'IsPrimary': True, 'Name': 'Trailer'}] |
1482 | UNITED STATES (USA) | None | 1482 | LIFT N LOCK, LLC | [] |
1483 | UNITED STATES (USA) | None | 1483 | CONTINENTAL BIOMASS INDUSTRIES, INC. | [] |
92 rows × 5 columns