🚗 CarsXE API (Python Package)

CarsXE is a powerful and developer-friendly API that gives you instant access to a wide range of vehicle data. From VIN decoding and market value estimation to vehicle history, images, OBD code explanations, and plate recognition, CarsXE provides everything you need to build automotive applications at scale.

🌐 Website: https://api.carsxe.com
📄 Docs: https://api.carsxe.com/docs
📦 All Products: https://api.carsxe.com/all-products

To get started with the CarsXE API, follow these steps:

1. Sign up for a CarsXE account:

   • Register here
   • Add a payment method to activate your subscription and get your API key.

2. Install the CarsXE pip package:

   Run this command in your terminal:

   pip install carsxe
   

3. Import the CarsXE API into your code:

   import asyncio
   from carsxe_api import CarsXE
   

4. Initialize the API with your API key:

   API_KEY = 'YOUR_API_KEY'
   carsxe = CarsXE(API_KEY)
   

5. Use the various endpoint methods provided by the API to access the data you need.

Usage

All API methods are asynchronous and must be called with await inside an async function or using asyncio.run().

Basic Example

import asyncio
from carsxe_api import CarsXE

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

# Run the async function
asyncio.run(main())

Alternative Usage (without async function)

import asyncio
from carsxe_api import CarsXE

carsxe = CarsXE('YOUR_API_KEY')
vin = 'WBAFR7C57CC811956'

try:
    vehicle = asyncio.run(carsxe.specs({"vin": vin}))
    print(vehicle["input"]["vin"])
except Exception as error:
    print(f"Error: {error}")

---

📚 Endpoints

The CarsXE API provides the following endpoint methods:

specs – Decode VIN & get full vehicle specifications

Required:

• vin

Optional:

• deepData
• disableIntVINDecoding

Example:

vehicle = await carsxe.specs({"vin": "WBAFR7C57CC811956"})
# or using asyncio.run()
vehicle = asyncio.run(carsxe.specs({"vin": "WBAFR7C57CC811956"}))

---

int_vin_decoder – Decode VIN with worldwide support

Required:

• vin

Optional:

• None

Example:

intvin = await carsxe.int_vin_decoder({"vin": "WF0MXXGBWM8R43240"})

---

plate_decoder – Decode license plate info (plate, country)

Required:

• plate
• country (always required except for US, where it is optional and defaults to 'US')

Optional:

• state (required for some countries, e.g. US, AU, CA)
• district (required for Pakistan)

Note:

• The state parameter is required only when applicable (for specific countries such as US, AU, CA, etc.).
• For Pakistan (country='pk'), both state and district are required.

Example:

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

---

market_value – Estimate vehicle market value based on VIN

Required:

• vin

Optional:

• state
• mileage
• condition ('excellent' | 'clean' | 'average' | 'rough')

Example:

marketvalue = await carsxe.market_value({"vin": "WBAFR7C57CC811956", "mileage": "50000", "condition": "clean"})

---

history – Retrieve vehicle history

Required:

• vin

Optional:

• None

Example:

history = await carsxe.history({"vin": "WBAFR7C57CC811956"})

---

images – Fetch images by make, model, year, trim

Required:

• make
• model

Optional:

• year
• trim
• color
• transparent
• angle
• photoType
• size
• license

Example:

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

---

recalls – Get safety recall data for a VIN

Required:

• vin

Optional:

• None

Example:

recalls = await carsxe.recalls({"vin": "1C4JJXR64PW696340"})

---

plate_image_recognition – Read & decode plates from images

Required:

• upload_url

Optional:

• None

Example:

plateimg = await carsxe.plate_image_recognition({"upload_url": "https://api.carsxe.com/img/apis/plate_recognition.JPG"})

---

vin_ocr – Extract VINs from images using OCR

Required:

• upload_url

Optional:

• None

Example:

vinocr = await carsxe.vin_ocr({"upload_url": "https://api.carsxe.com/img/apis/plate_recognition.JPG"})

---

year_make_model – Query vehicle by year, make, model and trim (optional)

Required:

• year
• make
• model

Optional:

• trim

Example:

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

---

obd_codes_decoder – Decode OBD error/diagnostic codes

Required:

• code

Optional:

• None

Example:

obdcode = await carsxe.obd_codes_decoder({"code": "P0115"})

---

lien_and_theft – Get lien and theft information for a VIN

Required:

• vin

Optional:

• None

Example:

lien_and_theft = await carsxe.lien_and_theft({"vin": "2C3CDXFG1FH762860"})

---

recalls_ymm – Get safety recall data by year, make, and model

Required:

• year
• make
• model

Optional:

• None

Example:

recalls_ymm = await carsxe.recalls_ymm({"year": "2026", "make": "toyota", "model": "corolla"})

---

submit_bulk_recall_batch – Submit up to 10,000 VINs for async recall checks

POST /v1/recalls-batch/submit

Required (at least one):

• vins (list of 17-character VIN strings)
• csv (inline CSV text)
• csvUrl (HTTPS URL to a CSV file)

Optional:

• webhookUrl

Example:

batch = await carsxe.submit_bulk_recall_batch({
    "vins": [
        "1HGBH41JXMN109186",
        "5YJSA1E26HF000001",
        "1C4JJXR64PW696340",
    ],
    "webhookUrl": "https://your-server.com/webhook",
})
batch_id = batch["data"]["batchId"]

---

get_bulk_recall_batch_status – Poll a recalls batch job

GET /v1/recalls-batch/status

Required:

• batchId

Optional:

• None

Example:

status = await carsxe.get_bulk_recall_batch_status({"batchId": batch_id})

---

get_bulk_recall_batch_results – Fetch completed batch results as JSON

GET /v1/recalls-batch/results

Required:

• batchId

Optional:

• None

Example:

results = await carsxe.get_bulk_recall_batch_results({"batchId": batch_id})

---

get_bulk_recall_batch_download – Download completed batch results as CSV

GET /v1/recalls-batch/download

Returns CSV text when the batch is complete, or a JSON error payload otherwise.

Required:

• batchId

Optional:

• None

Example:

csv_text = await carsxe.get_bulk_recall_batch_download({"batchId": batch_id})

---

ymm_options – Populate year / make / model / variant dropdowns

GET /v1/ymm-options

Each call returns one list. Omit filters to list years; add year for makes, make for models, and model for variants.

Required:

• None

Optional:

• dimension (years | makes | models | trims | variants)
• year
• make
• model
• trim

Example:

years = await carsxe.ymm_options({})
makes = await carsxe.ymm_options({"year": "2026"})
models = await carsxe.ymm_options({"make": "Toyota"})
variants = await carsxe.ymm_options({"year": "2026", "make": "Toyota", "model": "Tacoma"})

---

ownership_vin – Resolve registered owner(s) by VIN (enterprise)

GET /v1/ownership/vin

Required:

• vin

Optional:

• include (comma-separated: demographics, emails, phones, vehicle_history)

Example:

owners = await carsxe.ownership_vin({"vin": "1FT8X3BT0BEA61538"})

---

ownership_person – Resolve a person by name and address (enterprise)

GET /v1/ownership/person

Required:

• first_name
• last_name
• address
• zip

Optional:

• include

Example:

person = await carsxe.ownership_person({
    "first_name": "John",
    "last_name": "Sample",
    "address": "123 Example St",
    "zip": "90210",
})

---

ownership_address – Find residents at a street address (enterprise)

GET /v1/ownership/address

Required:

• address
• zip

Optional:

• include
• variant (legacy alias; prefer include)

Example:

residents = await carsxe.ownership_address({"address": "123 Example St", "zip": "90210"})

---

ownership_zip – Search people in a ZIP code (enterprise)

GET /v1/ownership/zip

Required:

• zip

Optional:

• gender (M or F)
• min_age
• max_age
• income
• page
• limit
• include
• variant (legacy alias; prefer include)

Example:

area = await carsxe.ownership_zip({"zip": "90210", "gender": "F", "min_age": "45"})

---

Notes & Best Practices

• Parameter requirements: Each endpoint requires specific parameters—see the Required/Optional fields above.
• Return values: All responses are Python dictionaries for easy access and manipulation.
• Error handling: Use try/except blocks to gracefully handle API errors.
• More info: For advanced usage and full details, visit the official API documentation.

---

Overall

CarsXE API provides a wide range of powerful, easy-to-use tools for accessing and integrating vehicle data into your applications and services. Whether you're a developer or a business owner, you can quickly get the information you need to take your projects to the next level—without hassle or inconvenience.