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

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

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

<CodeGroup title="Add the package">

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

```text {{ title: "Xcode" }}
File → Add Package Dependencies
https://github.com/carsxe/carsxe-swift-package
```

</CodeGroup>

## Quick start

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

## Error handling

Methods `throw` on API errors. Use `do/catch`:

```swift
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:

```bash
# .env or Xcode scheme environment variables
CARSXE_API_KEY=your_key_here
```

## 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).