Ендпойнти

Топ оферти

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.

Справочникът на ендпойнтите е на английски, както и самият API.

GET

/api/top-offers

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

Изисква обхвата top-offers scope.

Параметри

page / page_sizeinteger · query string

1-based page and rows per page, as alternatives to offset and limit. Do not combine page with offset or page_size with limit.

Пример 1 / 50·Откъде идва стойността Pagination state in your application.

sitestring · query string

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

Пример openlane·Откъде идва стойността /api/sites -> sites[].name

site_excludestring · query string

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

Пример copart·Откъде идва стойността /api/sites -> sites[].name

steeringenum · query string

Left- or right-hand drive, in any of the spellings /api/search accepts.

brandstring · query string

Exact clean_make, case-insensitive.

Пример BMW·Откъде идва стойността /api/search -> results[].clean_make

modelstring · query string

Exact clean_model, case-insensitive.

Пример 3 Series·Откъде идва стойността /api/search -> results[].clean_model

countrystring · query string

Vehicle country code, case-insensitive, matched exactly. Unlike /api/search, the europe pseudo-country is not supported here — it would match nothing. Pass ISO codes.

Пример DE·Откъде идва стойността /api/countries -> country_details[].code

year_from / year_tointeger · query string

First-registration year bounds.

Пример 2018 / 2024·Откъде идва стойността Year bounds chosen by your user.

kilometers_from / kilometers_tointeger · query string

Mileage bounds.

Пример 0 / 150000·Откъде идва стойността Mileage bounds chosen by your user.

price_from / price_tointeger · query string

Public EUR price bounds.

Пример 5000 / 25000·Откъде идва стойността EUR budget chosen by your user.

min_savings_pctinteger · query string

Only offers saving at least this percentage.

Пример 20·Откъде идва стойността Threshold chosen by your application.

sortenum · query string

Default savings_pct. An unknown value is a 400 listing the valid values.

Пример savings_pct·Откъде идва стойността Choose savings_pct, savings, price_low, price_high, or newest.

limit / offsetinteger · query string

Or page_size / page. Default 50, max 100 (up to 500 on a key granted bulk pages), offset capped at 5000. This envelope carries total, limit, offset and total_pages only — no page, page_size or max_page. Page by offset.

Пример 24 / 0·Откъде идва стойността 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

Примерен отговор

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
}

Какво получавате

results[]object[]

A standard search result card plus the top-offer fields below. One difference from a search card: no image annotations. These rows carry thumbnail_url as stored, but not served_thumbnail_url, not images[], and not image_status / image_source. Fetch photos from /api/auction/{site}/{id} (vault_gallery) or /api/auction-images.

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.