Swift Quickstart Guide
Get started with CarsXE's Swift package to integrate comprehensive vehicle data into your iOS, macOS, and other Swift applications.
The CarsXE Swift package provides a simple and powerful way to integrate vehicle data into your Swift applications across iOS, macOS, tvOS, and watchOS. This guide will help you get started quickly.
For more information, see the package on Swift Package Index.
Installation
Swift Package Manager
Add the CarsXE Swift Package to your project by adding this dependency to your Package.swift:
Package.swift
// Package.swift (example)
dependencies: [
.package(url: "https://github.com/carsxe/carsxe-swift-package.git", branch: "main")
]And include it in your target dependencies:
Package.swift
// Package.swift (targets example)
targets: [
.executableTarget(
name: "YourApp",
dependencies: [
.product(name: "carsxe", package: "carsxe-swift-package")
]
)
]Xcode
In Xcode, go to File → Add Packages... and enter:
https://github.com/carsxe/carsxe-swift-package.git
Setup
First, import the CarsXE package and initialize it with your API key:
ContentView.swift
import SwiftUI
import carsxe
struct ContentView: View {
// Initialize the client
let carsxe = CarsXE(apiKey: "YOUR_API_KEY_HERE")
var body: some View {
// Your UI code here
Text("CarsXE Example")
}
}Basic Usage
VIN Specifications
VehicleService.swift
import carsxe
class VehicleService {
private let carsxe = CarsXE(apiKey: "YOUR_API_KEY_HERE")
func decodeVIN() {
let vin = "WBAFR7C57CC811956"
do {
let vehicle = try carsxe.specs(["vin": vin])
if let input = vehicle["input"] as? [String: Any],
let vinValue = input["vin"] as? String {
print("VIN: \(vinValue)")
}
} catch {
print("Error: \(error)")
}
}
}International VIN Decoder
VehicleService.swift
func decodeInternationalVIN() {
do {
let intvin = try carsxe.intVinDecoder(["vin": "WF0MXXGBWM8R43240"])
print(intvin)
} catch {
print("Error: \(error)")
}
}Market Value
VehicleService.swift
func getMarketValue() {
do {
let marketvalue = try carsxe.marketValue(["vin": "WBAFR7C57CC811956"])
print(marketvalue)
} catch {
print("Error: \(error)")
}
}Vehicle History
VehicleService.swift
func getVehicleHistory() {
do {
let history = try carsxe.history(["vin": "WBAFR7C57CC811956"])
print(history)
} catch {
print("Error: \(error)")
}
}License Plate Decoder
VehicleService.swift
func decodePlate() {
do {
let decodedPlate = try carsxe.plateDecoder([
"plate": "7XER187",
"state": "CA",
"country": "US"
])
print(decodedPlate)
} catch {
print("Error: \(error)")
}
}Vehicle Images
VehicleService.swift
func getVehicleImages() {
do {
let images = try carsxe.images([
"make": "BMW",
"model": "X5",
"year": "2019"
])
print(images)
} catch {
print("Error: \(error)")
}
}Vehicle Recalls
VehicleService.swift
func getRecalls() {
do {
let recalls = try carsxe.recalls(["vin": "1C4JJXR64PW696340"])
print(recalls)
} catch {
print("Error: \(error)")
}
}Plate Image Recognition
VehicleService.swift
func recognizePlateFromImage() {
do {
let plateResult = try carsxe.plateImageRecognition(
imageUrl: "https://api.carsxe.com/img/apis/plate_recognition.JPG"
)
print(plateResult)
} catch {
print("Plate image error: \(error)")
}
}VIN OCR from Image
VehicleService.swift
func extractVINFromImage() {
do {
let vinocr = try carsxe.vinOCR(
imageUrl: "https://api.carsxe.com/img/apis/plate_recognition.JPG"
)
print(vinocr)
} catch {
print("VIN OCR error: \(error)")
}
}Year-Make-Model Search
VehicleService.swift
func searchByYearMakeModel() {
do {
let yymm = try carsxe.yearMakeModel([
"year": "2012",
"make": "BMW",
"model": "5 Series"
])
print(yymm)
} catch {
print("Error: \(error)")
}
}OBD Code Decoder
VehicleService.swift
func decodeOBDCode() {
do {
let obdcode = try carsxe.obdCodesDecoder(["code": "P0115"])
print(obdcode)
} catch {
print("Error: \(error)")
}
}Error Handling
The Swift package provides comprehensive error handling:
ErrorHandling.swift
import carsxe
class VehicleErrorHandler {
private let carsxe = CarsXE(apiKey: "YOUR_API_KEY")
func handleVINDecoding(vin: String) {
do {
let result = try carsxe.specs(["vin": vin])
print("Success: \(result)")
} catch {
handleError(error)
}
}
private func handleError(_ error: Error) {
let errorDescription = error.localizedDescription
if errorDescription.contains("400") {
print("Invalid VIN format")
} else if errorDescription.contains("401") {
print("Invalid API key")
} else if errorDescription.contains("429") {
print("Rate limit exceeded")
} else {
print("Unexpected error: \(errorDescription)")
}
}
}Environment Variables
Store your API key securely using environment variables:
Config.swift
import Foundation
enum Config {
static let carsxeAPIKey: String = {
guard let apiKey = ProcessInfo.processInfo.environment["CARSXE_API_KEY"] else {
fatalError("CARSXE_API_KEY not found in environment variables")
}
return apiKey
}()
}
// Usage
let carsxe = CarsXE(apiKey: Config.carsxeAPIKey)Available Endpoints
| Method | Description |
|---|---|
carsxe.specs(["vin": vin]) | Decode VIN & get full vehicle specifications |
carsxe.intVinDecoder(["vin": vin]) | Decode VIN with worldwide support |
carsxe.plateDecoder(["plate": plate, "state": state, "country": country]) | Decode license plate info |
carsxe.marketValue(["vin": vin]) | Estimate vehicle market value based on VIN |
carsxe.history(["vin": vin]) | Retrieve vehicle history |
carsxe.images(["make": make, "model": model, "year": year]) | Fetch images by make, model, year, trim |
carsxe.recalls(["vin": vin]) | Get safety recall data for a VIN |
carsxe.plateImageRecognition(imageUrl: url) | Read & decode plates from images |
carsxe.vinOCR(imageUrl: url) | Extract VINs from images using OCR |
carsxe.yearMakeModel(["year": year, "make": make, "model": model]) | Query vehicle by year, make, model and trim |
carsxe.obdCodesDecoder(["code": code]) | Decode OBD error/diagnostic codes |
Start building powerful automotive applications with CarsXE's Swift package!