CarsXE

The carsxe/carsxe Packagist package ships typed PHP 8.1 model classes for all CarsXE API responses. It does not bundle an HTTP client — use it alongside Guzzle (or any PSR-18 client) to make requests and hydrate the typed models from the JSON response. Requires PHP 8.1 or later.

Installation

composer require carsxe/carsxe guzzlehttp/guzzle

Quick start

<?php

require_once __DIR__ . '/vendor/autoload.php';

use CarsXE\Models\VehicleSpec;
use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://api.carsxe.com']);

$response = $client->get('/specs', [
    'query' => [
        'key' => $_ENV['CARSXE_API_KEY'],
        'vin' => 'WBAFR7C57CC811956',
    ],
]);

$body = json_decode((string) $response->getBody(), true);
$spec = VehicleSpec::fromArray($body['data']);

echo "{$spec->year} {$spec->make} {$spec->model}\n";

Available models

ClassDescription
VehicleSpecFull vehicle specification (VIN, make, model, engine, etc.)
BulkRecallBatchJobCompleted bulk recall batch job
BulkRecallBatchJobPendingIn-progress bulk recall batch job
BulkRecallBatchResultResult row for a single VIN in a batch
BulkRecallBatchRowRaw recall row within a batch result

Each class exposes a static fromArray(array $data): self factory method that maps the API response directly to typed readonly properties.

Additional endpoints

The same Guzzle pattern works for every CarsXE endpoint — just change the path and query parameters:

// Market value
$response = $client->get('/market-value', [
    'query' => [
        'key'      => $_ENV['CARSXE_API_KEY'],
        'vin'      => 'WBAFR7C57CC811956',
        'mileage'  => 45000,
        'state'    => 'CA',
    ],
]);

// Safety recalls
$response = $client->get('/recalls', [
    'query' => [
        'key' => $_ENV['CARSXE_API_KEY'],
        'vin' => 'WBAFR7C57CC811956',
    ],
]);

// Vehicle history
$response = $client->get('/history', [
    'query' => [
        'key' => $_ENV['CARSXE_API_KEY'],
        'vin' => 'WBAFR7C57CC811956',
    ],
]);

Error handling

Guzzle throws GuzzleHttp\Exception\ClientException on 4xx responses and GuzzleHttp\Exception\ServerException on 5xx:

use GuzzleHttp\Exception\GuzzleException;

try {
    $response = $client->get('/specs', [
        'query' => ['key' => $_ENV['CARSXE_API_KEY'], 'vin' => 'WBAFR7C57CC811956'],
    ]);
    $body = json_decode((string) $response->getBody(), true);
    $spec = VehicleSpec::fromArray($body['data']);
} catch (GuzzleException $e) {
    // $e->getCode() → HTTP status
    // $e->getMessage() → error details
    error_log('CarsXE error: ' . $e->getMessage());
}

Best practices

Load your key from the environment. Never hardcode it.

// .env (loaded via vlucas/phpdotenv or similar)
CARSXE_API_KEY=your_key_here
$apiKey = $_ENV['CARSXE_API_KEY'] ?? getenv('CARSXE_API_KEY');

Reuse the Guzzle client. Instantiate it once (e.g. in a service container) and inject it — Guzzle reuses the underlying cURL handle pool.