CarsXE

The carsxe gem is the official CarsXE client for Ruby. It wraps the REST API with idiomatic methods and handles authentication. Requires Ruby 2.7 or later.

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