The carsxe gem is the official CarsXE client for Ruby.

Installation

Add to your Gemfile:

gem 'carsxe'

Or install directly:

gem install carsxe

Quick start

require "carsxe"

carsxe = Carsxe::CarsXE.new(api_key: ENV["CARSXE_API_KEY"])

begin
  vehicle = carsxe.specs({ "vin" => "WBAFR7C57CC811956" })
  puts vehicle
rescue StandardError => error
  puts "Error: #{error.message}"
end

Methods

Core

Method	Description
`specs(params)`	Decode a 17-character VIN into full vehicle specifications
`market_value(params)`	Retail, trade-in, and auction value estimates
`recalls(params)`	Open safety recalls by VIN, make, model, or year
`plate_decoder(params)`	VIN lookup from a license plate (50+ countries)
`history(params)`	Title events, salvage, junk, and insurance records

Bulk recall batch

Method	Description
`submit_bulk_recall_batch(params)`	Submit a batch of VINs for recall lookup
`get_bulk_recall_batch_status(batch_id)`	Poll job status
`get_bulk_recall_batch_results(batch_id)`	Retrieve completed results
`get_bulk_recall_batch_download_url(batch_id)`	Get a CSV download URL

Endpoint examples

Runnable examples for each method. All of them assume the carsxe client from Quick start.

International VIN Decoder

intvin = carsxe.int_vin_decoder('vin' => 'WF0MXXGBWM8R43240')
puts intvin

Market Value

marketvalue = carsxe.market_value('vin' => 'WBAFR7C57CC811956')
puts marketvalue

Vehicle History

history = carsxe.history('vin' => 'WBAFR7C57CC811956')
puts history

License Plate Decoder

decoded_plate = carsxe.plate_decoder('plate' => '7XER187', 'state' => 'CA', 'country' => 'US')
puts decoded_plate

Vehicle Images

images = carsxe.images('make' => 'BMW', 'model' => 'X5', 'year' => '2019')
puts images

Vehicle Recalls

recalls = carsxe.recalls('vin' => '1C4JJXR64PW696340')
puts recalls

Plate Image Recognition

plateimg = carsxe.plate_image_recognition(
  'upload_url' => 'https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public'
)
puts plateimg

VIN OCR from Image

vinocr = carsxe.vin_ocr(
  'upload_url' => 'https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public'
)
puts vinocr

Year-Make-Model Search

yymm = carsxe.year_make_model('year' => '2012', 'make' => 'BMW', 'model' => '5 Series')
puts yymm

OBD Code Decoder

obdcode = carsxe.obd_codes_decoder('code' => 'P0115')
puts obdcode

Lien and Theft

lien_and_theft = carsxe.lien_and_theft('vin' => '2C3CDXFG1FH762860')
puts lien_and_theft

Error handling

The client raises StandardError on API errors. Wrap calls in a begin/rescue block:

begin
  vehicle = carsxe.specs({ "vin" => "WBAFR7C57CC811956" })
  puts vehicle
rescue StandardError => error
  puts "Error: #{error.message}"
end

Best practices

Load your key from the environment. Use ENV.fetch to surface misconfiguration immediately:

carsxe = Carsxe::CarsXE.new(api_key: ENV.fetch("CARSXE_API_KEY"))

Create one instance and reuse it across requests — the client manages the underlying connection pool.

Store your key in an environment variable. Never hardcode it or commit it to source control.

# .env
CARSXE_API_KEY=your_key_here