The carsxe package is the official CarsXE client for Python. It installs the carsxe_api module.

Installation

pip install carsxe
# uv add carsxe
# poetry add carsxe

Quick start

Construct the client with your API key. Every method is a coroutine, so await it (or run it with asyncio.run).

import asyncio
from carsxe_api import CarsXE

carsxe = CarsXE("YOUR_API_KEY")

async def main():
    vehicle = await carsxe.specs({"vin": "WBAFR7C57CC811956"})
    print(vehicle)

asyncio.run(main())

Methods

Each method is async and takes a single dict of parameters, returning the parsed JSON response.

Method	Params	Description
`specs(params)`	`{"vin", "deepdata"?, "disableIntVINDecoding"?}`	Decode a VIN into full vehicle specifications
`int_vin_decoder(params)`	`{"vin"}`	Decode a non-US international VIN
`market_value(params)`	`{"vin", "state"?, "mileage"?, "condition"?}`	Retail, trade-in, and auction value estimates
`history(params)`	`{"vin"}`	Title events, salvage, and insurance records
`recalls(params)`	`{"vin"}`	Open safety recalls by VIN
`lien_and_theft(params)`	`{"vin"}`	Lien records and theft/salvage status
`plate_decoder(params)`	`{"plate", "state"?, "country"?, "district"?}`	Resolve a license plate to vehicle data (`country` defaults to `US`)
`images(params)`	`{"make", "model", "year"?, "trim"?, "color"?, "angle"?, "photoType"?, "size"?, "transparent"?, "license"?}`	Vehicle photos by make, model, and year
`plate_image_recognition(params)`	`{"upload_url"}`	Extract plate info from an image URL
`vin_ocr(params)`	`{"upload_url"}`	Extract VIN text from an image via OCR
`year_make_model(params)`	`{"year", "make", "model"}`	Look up vehicles by year, make, and model
`obd_codes_decoder(params)`	`{"code"}`	Decode an OBD-II diagnostic trouble code

Endpoint examples

Runnable examples for each method. All of them assume the carsxe client from Quick start and are driven with asyncio.run(...).

International VIN Decoder

intvin = asyncio.run(carsxe.int_vin_decoder({"vin": "WF0MXXGBWM8R43240"}))
print(intvin)

Market Value

marketvalue = asyncio.run(carsxe.market_value({"vin": "WBAFR7C57CC811956"}))
print(marketvalue)

Vehicle History

history = asyncio.run(carsxe.history({"vin": "WBAFR7C57CC811956"}))
print(history)

License Plate Decoder

decoded_plate = asyncio.run(
    carsxe.plate_decoder({"plate": "7XER187", "state": "CA", "country": "US"})
)
print(decoded_plate)

Vehicle Images

images = asyncio.run(carsxe.images({"make": "BMW", "model": "X5", "year": "2019"}))
print(images)

Vehicle Recalls

recalls = asyncio.run(carsxe.recalls({"vin": "1C4JJXR64PW696340"}))
print(recalls)

Plate Image Recognition

plateimg = asyncio.run(
    carsxe.plate_image_recognition(
        {
            "upload_url": "https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public"
        }
    )
)
print(plateimg)

VIN OCR from Image

vinocr = asyncio.run(
    carsxe.vin_ocr(
        {
            "upload_url": "https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public"
        }
    )
)
print(vinocr)

Year-Make-Model Search

yymm = asyncio.run(
    carsxe.year_make_model({"year": "2012", "make": "BMW", "model": "5 Series"})
)
print(yymm)

OBD Code Decoder

obdcode = asyncio.run(carsxe.obd_codes_decoder({"code": "P0115"}))
print(obdcode)

Lien and Theft

lien_and_theft = asyncio.run(carsxe.lien_and_theft({"vin": "2C3CDXFG1FH762860"}))
print(lien_and_theft)

Error handling

Methods return the parsed JSON response. Wrap calls in try/except to catch network and request errors:

import asyncio
from carsxe_api import CarsXE

carsxe = CarsXE("YOUR_API_KEY")

async def main():
    try:
        vehicle = await carsxe.specs({"vin": "WBAFR7C57CC811956"})
        print(vehicle)
    except Exception as error:
        print(f"CarsXE error: {error}")

asyncio.run(main())

Best practices

Store your key in an environment variable. Never hardcode it or commit it to source control.

import os
from carsxe_api import CarsXE

carsxe = CarsXE(os.environ["CARSXE_API_KEY"])

# .env
CARSXE_API_KEY=your_key_here

Every method is asynchronous. Call them from within an async function and drive them with asyncio.run(...), or await them directly inside an existing event loop (FastAPI, async workers, notebooks).