search

Search live auction inventory

The primary search. Every parameter below is optional; a request with no filter at all returns the whole active inventory in feed order.

Depth policy is different here. The general public offset cap is pagination.max_offset from GET /api/contract (5000 by default), but an unfiltered search pages to any depth — it seeks a precomputed feed rank window rather than counting rows. A filtered search has no precomputed rank to seek into and stays bounded by that cap. Asking for a page too deep returns a 400 that says which of the two you are in.

Selecting sources. site and site_exclude take a comma-separated slug list, OR within the parameter. An unknown slug on either is a 400 naming the offender — one bad member rejects the whole list rather than quietly serving a different search. Sent together, the exclusion narrows the include list; excluding everything you included is a 400.

Embedded galleries are capped. Each result row's images array carries at most the first 8 display-ordered photos for first-paint convenience; the complete gallery lives on /api/auction/{site_slug}/{auction_id} (vault_gallery) and /api/auction-images/{site_slug}/{auction_id}.

get/api/search

Request

  • Base URL: https://api.thecarapi.com
  • URL: https://api.thecarapi.com/api/search
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer
    • API key in query parameter api_key

Query parameters

searchstring

Free-text query over brand, model and keywords.

sitestring
Example:openlane,ecarstrade

Comma-separated source slugs from /api/sites, OR within the parameter. Case-insensitive; padding and empty members are ignored. An unknown slug is a 400 naming the offender.

site_excludestring
Example:copart

Comma-separated source slugs to leave out. Same rules as site.

brandstring
Example:bmw

Brand display name, slug (from /api/brands), or numeric brand_id.

modelstring
Example:320d

Model name or slug.

year_frominteger
Example:2018

Lower bound on registration year, inclusive.

year_tointeger
Example:2024

Upper bound on registration year, inclusive.

production_year_frominteger
Example:2018

Lower bound on production year, inclusive. production_year falls back to the registration year where the source publishes no build year, with registration-year fallback when build-year evidence is absent.

production_year_tointeger
Example:2024

Upper bound on production year, inclusive.

fuelstring
Example:Diesel

Canonical fuel group from /api/fuels.

gearboxstring
Example:Automatic

Canonical gearbox group from /api/gearboxes.

countrystring
Example:DE

ISO country code from /api/countries, or the pseudo-country europe. Accepted and ignored by /api/sites and /load-models.

typestring
Example:520d

Trim / version, as listed by /api/types. Comma-separated values select several. Cars with no trim recorded are kept, so a trim filter narrows the list without hiding unclassified stock.

vehicle_type'cars' | 'suvs & trucks' | 'suvs and trucks'
body_stylestring
steering'left' | 'lhd' | 'left-hand' | 'left_hand' | 'right' | 'rhd' | 'right-hand' | 'right_hand'
Example:left

Which side the steering wheel is on. The parameter takes two values, left and right; lhd/left-hand/left_hand and rhd/right-hand/right_hand are equivalent spellings of them. Any other value is a 400.

Derived rather than stored. The side is taken from the car's registration market, so a car from an ISO country that drives on the left (GB, IE, JP, CY, MT, AU, NZ, ZA, IN, TH, HK, SG) is right and everything else is left. Every listing resolves to one side or the other, so the two values partition the inventory and their totals sum to the unfiltered total. The same value is published on each result as steering.

Accepted by /api/search, /api/listVehicles, /api/top-offers and every facet endpoint, which narrow their option lists by it. Sending it to a facet endpoint takes that request off the precomputed facet table and onto a live aggregate, so it is slower than an unfiltered facet call.

kilometers_frominteger

Lower bound on mileage in kilometres.

kilometers_tointeger

Upper bound on mileage in kilometres.

horsepower_frominteger
horsepower_tointeger
price_frominteger

Lower bound on the public EUR price.

price_tointeger

Upper bound on the public EUR price.

damagedboolean

true restricts to damaged/broken vehicles, false to undamaged ones. Also accepts 1/0/yes/no.

buy_nowboolean

true restricts to Buy-Now listings. Also accepts 1/0/yes/no.

ending_soonboolean

true restricts to auctions ending within roughly two hours.

smart_filter'top_offers' | 'low_mileage' | 'best_value'
is_activeboolean

The ended-lot switch, and the spelling most callers reach for. true (the default) hides lots whose auction has closed. false shows closed lots in addition to live ones — it does not return only ended lots, and it is not a filter on the is_active response field. Also accepts 1/0/yes/no.

include_endedboolean

The same switch inverted: include_ended=true == is_active=false. Sent together, include_ended wins. Also accepts 1/0/yes/no.

sort'default' | 'newest' | 'top_offers' | 'time_left_least' | 'time_left_desc' | 'time_left_most' | 'price_low' | 'price_high' | 'year_new' | 'year_old' | 'production_year_new' | 'production_year_old' | 'brand_az' | 'brand_za'

default orders listings with a photo first, then newest. The retired random value is still accepted and is served as default.

Result ordering. default is photo-first, then newest. The retired random value is still accepted and is served as default.

limitinteger

Page size. Capped at pagination.max_limit from GET /api/contract (100 by default); larger values are clamped down rather than rejected. Do not combine with page_size — that is a 400.

offsetinteger

0-based row offset. Do not combine with page — that is a 400. Bounded by pagination.max_offset (5000 by default) on archive, catalog, top-offers and classifieds; /api/search and /api/listVehicles have no offset cap.

pageinteger

1-based page number; maps to offset = (page - 1) * limit. Do not combine with offset.

page_sizeinteger

Alias for limit. Do not combine with limit.

include_totalboolean

false returns total: null and skips the count, which is faster.

count_onlyboolean

true returns the counts only, with no result rows.

Headers

If-None-Matchstring
Example:W/"6f1c0a9d8e"

Echo back the ETag from your last response for this URL. An unchanged page answers 304 Not Modified with no body. ETags are weak, so the tag stays valid whether or not the body came back compressed.

Response

Matching auctions.

successboolean required
contract_versionstring

Matches info.version of this document.

request_idstring

Also returned as the X-Request-ID header.

server_timestring date-time

UTC ISO-8601 timestamp of the response.

data_updated_atstring date-time

Route-supplied data timestamp, falling back to server_time. Not a guaranteed source refresh time; inspect listing observation timestamps and live_price.fetched_at where available.

totalinteger nullable

null when totals are suppressed or could not be computed.

limitinteger
offsetinteger
pageinteger
page_sizeinteger
total_pagesinteger nullable

null when total is null.

max_pageinteger nullable

Deepest page reachable under the offset policy.

count_onlyboolean

Example response

{
  "success": true,
  "contract_version": "2026-09-03",
  "results": [
    {
      "auction_id": 38112900,
      "site_name": "openlane",
      "clean_make": "BMW",
      "clean_model": "320d",
      "model_display": "320d M Sport",
      "registration_year": 2020,
      "production_year": 2019,
      "production_month": 11,
      "mileage": 45000,
      "fuel_group": "Diesel",
      "gearbox_group": "Automatic",
      "steering": "left",
      "public_price_eur": 21500,
      "auction_end_at": "2026-08-20T10:00:00Z",
      "country_code": "DE",
      "auction_id_str": "38112900"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.