CarsXE

The carsxe package is the official CarsXE client for Swift. It wraps the REST API with idiomatic methods and handles authentication. Requires Swift 5.5 or later.

Installation

Add the package

Code
dependencies: [
    .package(url: "https://github.com/carsxe/carsxe-swift-package", from: "1.0.0"),
],
targets: [
    .target(
        name: "YourTarget",
        dependencies: ["carsxe"]
    ),
]

Quick start

import carsxe

let carsxe = CarsXE(apiKey: ProcessInfo.processInfo.environment["CARSXE_API_KEY"]!)

do {
    let vehicle = try carsxe.specs(["vin": "WBAFR7C57CC811956"])
    print(vehicle)
} catch {
    print("Error: \(error)")
}

Methods

Core

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

Bulk recall batch

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

Error handling

Methods throw on API errors. Use do/catch:

do {
    let vehicle = try carsxe.specs(["vin": "WBAFR7C57CC811956"])
    print(vehicle)
} catch {
    print("CarsXE error: \(error)")
}

Best practices

Read the key from the environment or Keychain. For iOS/macOS apps, store the key in the Keychain rather than environment variables for production use.

Create one instance and reuse it — don't instantiate the client per request.

Store your key in an environment variable for development:

# .env or Xcode scheme environment variables
CARSXE_API_KEY=your_key_here