NHTSA Vin

A ruby gem for fetching and parsing vehicle identification via the vehicle identification number (VIN) from the NHTSA webservice. Note, this gem is not officially affiliated with the NHTSA.

Please note, this gem is currently in early development.

Installation

Add this line to your application's Gemfile:

gem 'nhtsa_vin'

And then execute:

bundle

Or install it yourself as:

gem install nhtsa_vin

Usage

Validation

Prior to dispatching a call to the web service, you can optionally validate a given VIN first. Calling #validate returns an NhtsaVin::Validation.

validation = NhtsaVin.validate('1J4BA5H11AL143811') # => <#NhtsaVin.Validate>
validation.valid? # => true

validation = NhtsaVin.validate('SOMEBADVIN') # => <#NhtsaVin.Validate>
validation.valid? # => false
validation.error # => 'Invalid VIN format'

Once validated, the validation also provides the components of a VIN, and additional information

validation = NhtsaVin.validate('1J4BA5H11AL143811') # => <#NhtsaVin.Validate>
validation.checksum # => '1'
validation.plant # => 'L'

Query

The main method for the gem is NhtsaVin::get, which takes a VIN string as the argument, and will return you a NhtsaVin::Query.

query = NhtsaVin.get('1J4BA5H11AL143811') # => <NhtsaVin::Query>
query.valid? # => true

The actual data from the web service is contained in the response method. This returns a struct containing the various interesting bits from the API.

query.response # => <Struct::NhtsaResponse make="Jeep", model="Grand Cherokee", trim="Laredo/Rocky Mountain Edition", type="SUV", year="2008", size=nil, ... doors=4>

They query object also contains helper methods for error handling. For example, in the result no match is found, the result will be nil, and #valid? will return false.

query = NhtsaVin.get('SOME_BAD_VIN') # => <NhtsaVin::Query>
query.valid? # => false
query.error_code # => 11
query.error # => "11- Incorrect Model Year, decoded data may not be accurate"

Vehicle Types

For brevity, we're reducing the Vehicle Type response to an enumerated set of ["Car", "Truck", "Van", "SUV", "Minivan"]. We're doing a rough parse of the type and body style to achieve this. It's probably not perfect.

License

Licensed under the MIT License.