CarsXE

The carsxe artifact is the official CarsXE client for Java. It wraps the REST API with typed methods and handles authentication. Requires Java 11 or later.

Installation

Add the dependency

Code
<dependency>
  <groupId>io.github.carsxe</groupId>
  <artifactId>carsxe</artifactId>
  <version>LATEST</version>
</dependency>

Quick start

import io.github.carsxe.CarsXE;
import java.util.HashMap;
import java.util.Map;

public class Main {
    public static void main(String[] args) {
        CarsXE carsxe = new CarsXE(System.getenv("CARSXE_API_KEY"));
        Map<String, String> params = new HashMap<>();
        params.put("vin", "WBAFR7C57CC811956");

        try {
            Map<String, Object> vehicle = carsxe.specs(params);
            System.out.println(vehicle);
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Methods

Core

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

Bulk recall batch

MethodDescription
submitBulkRecallBatch(params)Submit a batch of VINs for recall lookup
getBulkRecallBatchStatus(batchId)Poll job status
getBulkRecallBatchResults(batchId)Retrieve completed results
getBulkRecallBatchDownloadUrl(batchId)Get a CSV download URL

Error handling

Methods throw Exception on API errors. Wrap calls in a try/catch block:

try {
    Map<String, Object> vehicle = carsxe.specs(params);
    System.out.println(vehicle);
} catch (Exception e) {
    System.err.println("Error: " + e.getMessage());
}

Best practices

Validate the environment variable at startup.

String apiKey = System.getenv("CARSXE_API_KEY");
if (apiKey == null || apiKey.isBlank()) {
    throw new IllegalStateException("CARSXE_API_KEY is not set");
}
CarsXE carsxe = new CarsXE(apiKey);

Create one instance and reuse it. The client manages connection pooling internally — don't instantiate per request.

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