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

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
pvaw		pvaw
tests		tests
.gitignore		.gitignore
LICENSE.txt		LICENSE.txt
README.md		README.md
demo.ipynb		demo.ipynb
setup.cfg		setup.cfg
setup.py		setup.py

License

michaelmicheal/PythonVehicleAPIWrapper

Folders and files

Latest commit

History

Repository files navigation

PVAW: Python Vehicle API Wrapper

License

Documentation

Istalling PVAW

Importing PVAW

Vin Decoding

Vin Class

class pvaw.Vin(full_or_partial_vin, model_year=None)

Constructing a Vin

Decoding a Vin

pvaw.Vin.decode()

Batch Decoding

pvaw.decode_vins(vins)

WMI Methods

WMI Decoding

pvaw.decode_wmi(wmi)

Finding WMIs by Manufacturer

pvaw.get_wmis(manufacturer_search)

Make Methods

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

Manufacturer Methods

Getting Manufacturers

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

Searching for Specific Manufacturers

pvaw.get_manufacturer_details(manufacturer_name_or_id)

About

Resources

License

Stars

Watchers

Forks

Languages