Endpoints

Top offers

Live auctions our pipeline judged to be priced below their market reference. Same deals as /api/search?sort=top_offers, but each card additionally carries the reference the verdict was made against.

GET

/api/top-offers

Feed of auctions priced below their market reference, newest comparison first.

Requires the top-offers scope.

Parameters

sitestring · query string

Comma-separated source slugs. An unknown value returns 400.

Example ecarstrade·Where the value comes from /api/sites -> sites[].name

site_excludestring · query string

Comma-separated source slugs to leave out. Same rules as on /api/search.

Example copart·Where the value comes from /api/sites -> sites[].name

steeringenum · query string

Left- or right-hand drive.

Example left·Where the value comes from left | lhd | right | rhd — any other value is a 400.

brandstring · query string

Exact clean_make, case-insensitive.

Example BMW·Where the value comes from /api/search -> results[].clean_make

modelstring · query string

Exact clean_model, case-insensitive.

Example 3 Series·Where the value comes from /api/search -> results[].clean_model

countrystring · query string

Vehicle country code, case-insensitive.

Example DE·Where the value comes from /api/countries -> country_details[].code

year_from / year_tointeger · query string

First-registration year bounds.

Example 2018 / 2024·Where the value comes from Year bounds chosen by your user.

kilometers_from / kilometers_tointeger · query string

Mileage bounds.

Example 0 / 150000·Where the value comes from Mileage bounds chosen by your user.

price_from / price_tointeger · query string

Public EUR price bounds.

Example 5000 / 25000·Where the value comes from EUR budget chosen by your user.

min_savings_pctinteger · query string

Only offers saving at least this percentage.

Example 20·Where the value comes from Threshold chosen by your application.

sortenum · query string

Default savings_pct.

Example savings_pct·Where the value comes from Choose savings_pct, savings, price_low, price_high, or newest.

limit / offsetinteger · query string

Or page_size / page. limit caps at 100.

Example 24 / 0·Where the value comes from Pagination state in your application.

Example requests

Request

GET https://api.thecarapi.com/api/top-offers?site=openlane&min_savings_pct=20&limit=24

GET https://api.thecarapi.com/api/top-offers?brand=BMW&country=DE&sort=savings&page=2&page_size=20

Example response

json

{
  "success": true,
  "results": [
    {
      "auction_id": 8842711,
      "site_name": "openlane",
      "car_name_en": "BMW 320d Touring",
      "clean_make": "BMW",
      "clean_model": "3 Series",
      "public_price_eur": 9000,
      "is_top_offer": true,
      "top_offer_savings": 2500,
      "top_offer_savings_pct": 21.7,
      "market_reference": {
        "price_eur": 11500,
        "mileage": 165000,
        "km_difference": -15000,
        "explanation": "Rule: this car must save at least 1,800 EUR — ..."
      }
    }
  ],
  "total": 318,
  "limit": 24,
  "offset": 0,
  "total_pages": 14
}

What you get back

results[]object[]

A standard search result card — every field documented in the data dictionary — plus the top-offer fields below.

is_top_offerboolean

Always true on this feed. Also present on /api/search cards.

top_offer_savingsnumber

Absolute EUR saving against the market reference.

top_offer_savings_pctnumber

Saving as a percentage of the reference price. Default sort key.

market_reference.price_eurnumber

The reference price this car was measured against.

market_reference.mileageinteger

The reference mileage, so you can judge whether the comparison is like-for-like.

market_reference.km_differenceinteger

This car’s mileage minus the reference. Negative means this car has done fewer kilometres.

market_reference.explanationstring

The rule that admitted this car to the feed, in words — e.g. the minimum EUR saving it had to clear.