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

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

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

Endpoint examples

Runnable examples for each method. All of them assume the carsxe instance from Quick start and are shown without the surrounding do/catch for brevity — every call is try.

International VIN Decoder

let intvin = try carsxe.intVinDecoder(["vin": "WF0MXXGBWM8R43240"])
print(intvin)

Market Value

let marketvalue = try carsxe.marketValue(["vin": "WBAFR7C57CC811956"])
print(marketvalue)

Vehicle History

let history = try carsxe.history(["vin": "WBAFR7C57CC811956"])
print(history)

License Plate Decoder

let decodedPlate = try carsxe.plateDecoder([
    "plate": "7XER187",
    "state": "CA",
    "country": "US",
])
print(decodedPlate)

Vehicle Images

let images = try carsxe.images([
    "make": "BMW",
    "model": "X5",
    "year": "2019",
])
print(images)

Vehicle Recalls

let recalls = try carsxe.recalls(["vin": "1C4JJXR64PW696340"])
print(recalls)

Plate Image Recognition

Takes a labelled imageUrl argument rather than a dictionary.

let plateResult = try carsxe.plateImageRecognition(
    imageUrl: "https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public"
)
print(plateResult)

VIN OCR from Image

let vinocr = try carsxe.vinOCR(
    imageUrl: "https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public"
)
print(vinocr)

Year-Make-Model Search

let yymm = try carsxe.yearMakeModel([
    "year": "2012",
    "make": "BMW",
    "model": "5 Series",
])
print(yymm)

OBD Code Decoder

let obdcode = try carsxe.obdCodesDecoder(["code": "P0115"])
print(obdcode)

Lien and Theft

let lienTheft = try carsxe.lienAndTheft(["vin": "2C3CDXFG1FH762860"])
print(lienTheft)

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