CarsXE Developer

Ruby Quickstart Guide

Get started with CarsXE's Ruby gem to integrate comprehensive vehicle data into your Ruby applications.

The CarsXE Ruby gem provides a simple and powerful way to integrate vehicle data into your Ruby applications. This guide will help you get started quickly.

For more information, see the gem on RubyGems.

Installation

Install the CarsXE Ruby gem using gem or bundler:

gem install carsxe

Or add it to your Gemfile:

Gemfile

gem 'carsxe'

Then run bundle install.

Setup

First, require the CarsXE client and initialize it with your API key:

app.rb

require 'carsxe' # Initialize the client
API_KEY = 'YOUR_API_KEY_HERE'
carsxe = Carsxe::CarsXE.new(api_key: API_KEY)

Basic Usage

VIN Specifications

app.rb

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

International VIN Decoder

app.rb

begin
  intvin = carsxe.int_vin_decoder('vin' => 'WF0MXXGBWM8R43240')
  puts intvin
rescue StandardError => error
  puts "Error: #{error.message}"
end

Market Value

app.rb

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

Vehicle History

app.rb

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

License Plate Decoder

app.rb

begin
  decoded_plate = carsxe.plate_decoder('plate' => '7XER187', 'state' => 'CA', 'country' => 'US')
  puts decoded_plate
rescue StandardError => error
  puts "Error: #{error.message}"
end

Vehicle Images

app.rb

begin
  images = carsxe.images('make' => 'BMW', 'model' => 'X5', 'year' => '2019')
  puts images
rescue StandardError => error
  puts "Error: #{error.message}"
end

Vehicle Recalls

app.rb

begin
  recalls = carsxe.recalls('vin' => '1C4JJXR64PW696340')
  puts recalls
rescue StandardError => error
  puts "Error: #{error.message}"
end

Plate Image Recognition

app.rb

begin
  plateimg = carsxe.plate_image_recognition('upload_url' =>
  'https://api.carsxe.com/img/apis/plate_recognition.JPG')
  puts plateimg
rescue StandardError => error
  puts "Error: #{error.message}"
end

VIN OCR from Image

app.rb

begin
  vinocr = carsxe.vin_ocr('upload_url' => 'https://api.carsxe.com/img/apis/plate_recognition.JPG')
  puts vinocr
rescue StandardError => error
  puts "Error: #{error.message}"
end

Year-Make-Model Search

app.rb

begin
  yymm = carsxe.year_make_model('year' => '2012', 'make' => 'BMW', 'model' => '5 Series')
  puts yymm
rescue StandardError => error
  puts "Error: #{error.message}"
end

OBD Code Decoder

app.rb

begin
  obdcode = carsxe.obd_codes_decoder('code' => 'P0115')
  puts obdcode
rescue StandardError => error
  puts "Error: #{error.message}"
end

Error Handling

The Ruby gem provides comprehensive error handling:

error_handling.rb

require 'carsxe'
carsxe = Carsxe::CarsXE.new(api_key: 'YOUR_API_KEY')
begin
  result = carsxe.specs('vin' => 'INVALID_VIN')
  puts result
rescue StandardError => error
  case error.message
  when /400/
    puts "Invalid VIN format"
  when /401/
    puts "Invalid API key"
  when /429/
    puts "Rate limit exceeded"
  else
    puts "Unexpected error: #{error.message}"
  end
end

Environment Variables

Store your API key securely using environment variables:

.env

# .env file 
CARSXE_API_KEY=your_api_key_here

app.rb

require 'dotenv/load' 
require 'carsxe' 
carsxe = Carsxe::CarsXE.new(api_key: ENV['CARSXE_API_KEY'])

Available Endpoints

MethodDescription
carsxe.specs('vin' => vin)Decode VIN & get full vehicle specifications
carsxe.int_vin_decoder('vin' => vin)Decode VIN with worldwide support
carsxe.plate_decoder('plate' => plate, 'state' => state, 'country' => country)Decode license plate info
carsxe.market_value('vin' => vin)Estimate vehicle market value based on VIN
carsxe.history('vin' => vin)Retrieve vehicle history
carsxe.images('make' => make, 'model' => model, 'year' => year)Fetch images by make, model, year, trim
carsxe.recalls('vin' => vin)Get safety recall data for a VIN
carsxe.plate_image_recognition('upload_url' => url)Read & decode plates from images
carsxe.vin_ocr('upload_url' => url)Extract VINs from images using OCR
carsxe.year_make_model('year' => year, 'make' => make, 'model' => model)Query vehicle by year, make, model and trim
carsxe.obd_codes_decoder('code' => code)Decode OBD error/diagnostic codes

Start building powerful automotive applications with CarsXE's Ruby gem!

Python QuickstartSwift Quickstart