CarsXECarsXE

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

MethodDescription
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

MethodDescription
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

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