carauctions

Python client for TheCarApi — live car auction inventory from Copart, OpenLane, Auto1, Encar, eCarsTrade, Schadeautos and CarVector in one API.

Search hundreds of thousands of live lots across Europe, South Korea and Japan. Filter by brand, model, year, mileage, fuel, price and damage state. Pull full vehicle detail, image galleries, price history, VIN history, market price references and landed import costs.

pip install carauctions

Quickstart

from carauctions import CarAuctionsClient

client = CarAuctionsClient(api_key="YOUR_KEY")

page = client.search(brand="BMW", year_from=2018, fuel="Diesel", limit=5)

for car in page:
    print(car["car_name_en"], car["registration_year"], car["public_price_eur"], "EUR")

print(f"{page.total} matching lots")

BMW 320d Touring 2019 14350.0 EUR
BMW 520d xDrive   2018 16900.0 EUR
BMW X3 xDrive20d  2020 24100.0 EUR
BMW 118d          2019  9800.0 EUR
BMW 330e          2021 27450.0 EUR
18342 matching lots

Getting a key

Keys are issued per customer, and a free trial key is available.

→ Request a free trial key

Once you have it, either pass it in directly or export it:

export CARAUCTIONS_API_KEY="your-key"

client = CarAuctionsClient()   # picks the key up from the environment

What you can pull

Search and filter

page = client.search(
    brand="Audi",
    model="A4",
    year_from=2017, year_to=2022,
    kilometers_to=150_000,
    price_from=5000, price_to=20_000,
    fuel="Diesel",
    gearbox="Automatic",
    country="DE",
    site="openlane,auto1",     # only these sources
    damaged=False,
    buy_now=True,
    sort="price_low",
    limit=50,
)

Every result row carries auction_id, site_name, clean_make, clean_model, registration_year, mileage, hp, fuel_group, gearbox_group, public_price_eur, buy_now_price, current_price, thumbnail_url, auction_end_at, is_broken and more.

Page through everything

iter_search handles paging for you and yields one vehicle at a time:

for car in client.iter_search(brand="Toyota", fuel="Hybrid", max_results=500):
    print(car["auction_id"], car["public_price_eur"])

Full lot detail

lot = client.auction("openlane", "1234567")

print(lot["chassis_number"], lot["co2"], lot["cylinder_capacity"])
print(len(lot["gallery_images"]), "photos")

history = client.price_history("openlane", "1234567")
images  = client.auction_images("openlane", "1234567")

Underpriced lots

top_offers returns only cars priced below their market reference, with the reference attached:

for car in client.top_offers(min_savings_pct=20, site="openlane", limit=10):
    print(car["car_name_en"], f"-{car['top_offer_savings_pct']}%")

VIN history

client.vin_history("WBA8E9G50GNT12345")

Import cost calculator

quote = client.calculate(price=15000, origin="KR", destination="BG", site_name="encar")
print(quote["breakdown"]["estimated_total"])

Filter options and catalog

client.brands()                 # every brand with counts
client.models(brand="BMW")      # models for a brand
client.sites()                  # available auction sources + live counts
client.facets(brand="BMW")      # all facets for a query in one request
client.manufacturers()          # manufacturer catalog

Sources

Errors

Every failure is a typed exception carrying the API's message and the request id you should quote when reporting a problem:

from carauctions import RateLimited, PermissionDenied, InvalidRequest

try:
    page = client.search(site="ebay")
except InvalidRequest as e:
    print(e.message)       # "Unknown site 'ebay'. Valid sites: auto1, copart, ..."
    print(e.request_id)
except RateLimited as e:
    time.sleep(e.retry_after)
except PermissionDenied:
    print("Your key does not cover this endpoint")

AuthenticationError, PermissionDenied, NotFound, InvalidRequest, RateLimited and ServerError all inherit from CarAuctionsError.

Rate limits

The quota window from the last response is always available, so you can throttle yourself before you get a 429:

client.search(brand="BMW")
print(client.rate_limit.remaining, "requests left until", client.rate_limit.reset)

Requests that hit a 429 or a 5xx are retried automatically, honouring Retry-After. When a key is nearly exhausted you get one standard Python warning on stderr, so a long-running job tells you before it stalls rather than after.

Documentation

Full endpoint reference, field dictionary and response schemas: thecarapi.com/docs

License

MIT