---
title: "Java"
description: "Official CarsXE SDK for Java."
canonical_url: "https://docs.carsxe.com/docs/sdks/java"
markdown_url: "https://docs.carsxe.com/docs/sdks/java.md"
last_updated: "1980-01-01"
---

# Java
URL: /docs/sdks/java
LLM index: /llms.txt
Description: Official CarsXE SDK for Java.

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

<CodeGroup title="Add the dependency">

```xml {{ title: "Maven" }}
<dependency>
  <groupId>io.github.carsxe</groupId>
  <artifactId>carsxe</artifactId>
  <version>LATEST</version>
</dependency>
```

```groovy {{ title: "Gradle" }}
implementation 'io.github.carsxe:carsxe:LATEST'
```

</CodeGroup>

## Quick start

```java
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

| Method | Description |
|---|---|
| `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

| Method | Description |
|---|---|
| `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:

```java
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.**

```java
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.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).