TheCarApiVehicle data engine

Sign in Start free

contract 2026-10-05

Endpoints

Historical inventory

Ended listings moved into the archive, separate from ended rows still in the live table. Requires the archive scope. A last observed price is not a confirmed sale price.

GET

/api/archive/search

Search ended auctions

Requires the archive scope.

Parameters

auction_gradestring · query string

The Japanese auction house's grade, as a comma-separated list of the grades to keep: `S`, `6`, `5`, `4.5`, `4`, `3.5`, `3`, `2`, `1`, `R` and `RA` (repaired) and `***` (ungraded). Matched exactly, not as a minimum, because the letters have no place on the numeric scale. Case and full-width digits are folded; any other value is a 400 on `/api/search` and `/api/archive/search`, and ignored by the facet endpoints. Only Japanese listings carry a grade, so any value keeps only them. The grade is the resellers' where they state one they agree on, else the one read off the lot's auction sheet. It is published on each result as `auction_grade`. Not in the precomputed search index, so a request that sends it is served by the live query and is slower.

Example 4,4.5,5·Where the value comes from Listing values or your application settings.

auction_housestring · query string

The Japanese auction house, as a comma-separated list of names in the slug form each result's `auction_house` carries (`uss_tokyo`, `honda_tokyo`). Spaces, case and punctuation are folded, so `HONDA TOKYO` works too. Matches whole words of the house name: `uss` finds every USS branch, `tokyo` every Tokyo house, `uss_tokyo` that one house; `oky` finds nothing. A value that is not a Latin-script name is a 400 on `/api/search` and `/api/archive/search`, and ignored by the facet endpoints. Only Japanese listings carry a house, so any value keeps only them. Not in the precomputed search index, so a request that sends it is served by the live query and is slower.

Example uss,honda_tokyo·Where the value comes from Listing values or your application settings.

damagedboolean · query string

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

Example ·Where the value comes from Listing values or your application settings.

engine_fromnumber · query string

Smallest engine in litres, e.g. `1.6` (matches from 1550 cc).

Example ·Where the value comes from Listing values or your application settings.

engine_tonumber · query string

Largest engine in litres, e.g. `2.0` (matches up to 2049 cc).

Example ·Where the value comes from Listing values or your application settings.

horsepower_frominteger · query string

Example ·Where the value comes from Listing values or your application settings.

horsepower_tointeger · query string

Example ·Where the value comes from Listing values or your application settings.

lot_numberstring · query string

The Japanese auction house's lot number, as a comma-separated list. Leading zeros and full-width digits are folded (`080041` finds `80041`); a value that is not letters and digits is a 400 on `/api/search` and `/api/archive/search`, and ignored by the facet endpoints. Only Japanese listings carry a lot number, so any value keeps only them. A house numbers its lots per sale day, so one number can match several cars: tell them apart by `auction_house` and `batch_end_date` (the sale day) on each result. It is published on each result as `lot_number`. Not in the precomputed search index, so a request that sends it is served by the live query and is slower.

Example 80041·Where the value comes from Listing values or your application settings.

model_codestring · query string

A Japanese lot's chassis model code (e.g. `USF40`, `ZC6`), as a comma-separated list. Compared without case or punctuation, so `u-30-5` finds `U-30-5`. A value with no letters or digits is a 400 on `/api/search` and `/api/archive/search`, and ignored by the facet endpoints. Only Japanese listings carry a model code, so any value keeps only them. Published on each result as `model_code`. Not in the precomputed search index, so a request that sends it is served by the live query and is slower.

Example USF40,ZC6·Where the value comes from Listing values or your application settings.

sitestring · query string

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.

Example openlane,auto1·Where the value comes from Current API reference

site_excludestring · query string

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

Example copart·Where the value comes from Current API reference

brandstring · query string

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

Example bmw·Where the value comes from Current API reference

modelstring · query string

Model name or slug.

Example 320d·Where the value comes from Current API reference

countrystring · query string

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

Example DE·Where the value comes from Current API reference

fuelstring · query string

Canonical fuel group from `/api/fuels`.

Example Diesel·Where the value comes from Current API reference

gearboxstring · query string

Canonical gearbox group from `/api/gearboxes`.

Example Automatic·Where the value comes from Current API reference

year_frominteger · query string

Lower bound on registration year, inclusive.

Example 2018·Where the value comes from Current API reference

year_tointeger · query string

Upper bound on registration year, inclusive.

Example 2024·Where the value comes from Current API reference

production_year_frominteger · query string

Lower bound on production year, inclusive. `production_year` falls back to the registration year where the source publishes no build year, so missing build-year evidence falls back to the registration-year dimension.

Example 2018·Where the value comes from Current API reference

production_year_tointeger · query string

Upper bound on production year, inclusive.

Example 2024·Where the value comes from Current API reference

kilometers_frominteger · query string

Lower bound on mileage in kilometres.

Example 0·Where the value comes from Current API reference

kilometers_tointeger · query string

Upper bound on mileage in kilometres.

Example 150000·Where the value comes from Current API reference

price_frominteger · query string

Lower bound on the public EUR price.

Example 1000·Where the value comes from Current API reference

price_tointeger · query string

Upper bound on the public EUR price.

Example 30000·Where the value comes from Current API reference

archived_fromstring · query string

Only lots archived on or after this date (`YYYY-MM-DD`). Anything else is a `400`.

Example 2026-07-01·Where the value comes from Current API reference

archived_tostring · query string

Only lots archived on or before this date (`YYYY-MM-DD`). Inclusive of the whole day named.

Example 2026-08-31·Where the value comes from Current API reference

vinstring · query string

Exact full-VIN filter. Punctuation and case are ignored. A value that is not a valid 17-character VIN is a `400`. VIN coverage varies; query /api/archive/stats before relying on it.

Example WBA8E9G50GNU12345·Where the value comes from Current API reference

sortstring · query string

Result ordering.

Example archived_desc·Where the value comes from Current API reference

limitinteger · query string

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

Example 20·Where the value comes from Current API reference

offsetinteger · query string

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.

Example 0·Where the value comes from Current API reference

pageinteger · query string

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

Example 1·Where the value comes from Current API reference

page_sizeinteger · query string

Alias for `limit`. Do not combine with `limit`.

Example 20·Where the value comes from Current API reference

include_totalboolean · query string

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

Example true·Where the value comes from Current API reference

Example requests

Request

GET https://api.thecarapi.com/api/archive/search?site=japan&year_from=2020&limit=20

GET https://api.thecarapi.com/api/archive/search?brand=bmw&archived_from=2026-09-01

Example response

json

{
  "success": true,
  "results": [],
  "total": 0,
  "limit": 20,
  "offset": 0,
  "sort": "archived_desc",
  "page": 1,
  "page_size": 20,
  "total_pages": 0,
  "max_page": 0,
  "contract_version": "2026-10-05"
}

Notes

The historical counterpart to `/api/search`. It reads `auctions_archive`, which holds lots that ended, stayed inactive for the retention window, and were moved out of the live table with an `archived_at` stamp. Nothing here is buyable. **This is not a sold-price index.** `public_price_eur` is the last public price observed. `final_price` may be absent or have an unverified result basis; it is not proof of a completed sale. Call `/api/archive/stats` for the per-source coverage before building anything on a particular field. **No free-text `search` parameter.** The archive carries no trigram index, and a substring scan across it costs seconds. `brand` and `model` match exactly (case- and slug-insensitive), as they do on `/api/search`. Default ordering is newest-archived first. The general offset cap (`pagination.max_offset`, 5000 by default) applies — there is no unfiltered deep-paging path here.

GET

/api/archive/auction/{site_slug}/{auction_id}

One archived auction in full

Requires the archive scope.

Parameters

site_slugstring · in the URL pathrequired

Example openlane·Where the value comes from Current API reference

auction_idinteger · in the URL pathrequired

The source's auction id, as published on the search card.

Example 38112900·Where the value comes from Current API reference

Example request

Request

GET https://api.thecarapi.com/api/archive/auction/encar/38112900

Example response

json

{
  "success": true,
  "auction": {
    "site_name": "encar",
    "auction_id": 38112900,
    "auction_id_str": "38112900",
    "archived": true,
    "archived_at": "2026-09-01T12:00:00",
    "final_price": null
  },
  "contract_version": "2026-10-05"
}

GET

/api/archive/facets

Counts of finished lots per filter value.

Requires the archive scope.

Parameters

site / site_excludestring · query string

Comma-separated source slugs to include or leave out. An unknown slug is a 400 naming the offender.

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

brand / modelstring · query string

Brand name, slug or brand_id, and model name or slug, matched exactly as on /api/archive/search. Giving brand adds a model facet.

Example bmw / 320d·Where the value comes from /api/brands -> brands[].slug, /api/models?brand=bmw -> models[].slug

countrystring · query string

ISO country code or europe.

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

fuel / gearboxstring · query string

Canonical fuel and gearbox groups.

Example Diesel·Where the value comes from /api/fuels -> fuels[], /api/gearboxes -> gearboxes[]

year_from / year_tointeger · query string

Registration-year range, inclusive.

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

production_year_from / production_year_tointeger · query string

Production-year range. Falls back to registration year where the source publishes no build year.

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

kilometers_from / kilometers_tointeger · query string

Mileage range in kilometres.

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

price_from / price_tointeger · query string

Public EUR price range.

Example 1000 / 30000·Where the value comes from EUR budget chosen by your user.

horsepower_from / horsepower_tointeger · query string

Power range in HP.

Example 150 / 300·Where the value comes from Power bounds chosen by your user.

engine_from / engine_tonumber · query string

Engine size in litres. 1.6 matches from 1550 cc; 2.0 matches up to 2049 cc.

Example 1.6 / 2.0·Where the value comes from Engine sizes chosen by your user.

damagedboolean · query string

true keeps only damaged or broken vehicles, false only undamaged ones.

Example false·Where the value comes from Your filter choice.

archived_from / archived_tostring · query string

Lots that ended on or after / on or before this date (YYYY-MM-DD).

Example 2026-07-01 / 2026-09-30·Where the value comes from Date range chosen by your user.

vinstring · query string

Exact full-VIN filter.

Example WBA8E9G50GNU12345·Where the value comes from A VIN you already have.

limitinteger · query string

Values per facet. Default 100, maximum 500.

Example 100·Where the value comes from How many values your control can hold.

Example requests

Request

GET https://api.thecarapi.com/api/archive/facets?brand=bmw&year_from=2018

GET https://api.thecarapi.com/api/archive/facets?site=copart&archived_from=2026-07-01

Example response

json

{
  "success": true,
  "total": 48210,
  "facets": {
    "site": [
      {
        "value": "openlane",
        "count": 18220
      }
    ],
    "brand": [
      {
        "value": "BMW",
        "count": 48210
      }
    ],
    "model": [
      {
        "value": "320d",
        "count": 3120
      }
    ],
    "country": [
      {
        "value": "DE",
        "count": 11840
      }
    ],
    "fuel": [
      {
        "value": "Diesel",
        "count": 30110
      }
    ],
    "gearbox": [
      {
        "value": "Automatic",
        "count": 35020
      }
    ],
    "year": [
      {
        "value": 2019,
        "count": 6120
      }
    ],
    "condition": [
      {
        "value": "normal",
        "count": 44090
      }
    ]
  }
}

What you get back

totalinteger

Finished lots matching the filters.

facets.<dimension>{value, count}[]

site, brand, country, fuel, gearbox, year and condition, plus model when brand is given — the values present under the other filters, biggest first.

GET

/api/archive/statistics

Closing-price statistics of finished lots, grouped by one dimension.

Requires the archive scope.

Parameters

group_byenum · query string

The dimension to group by. Default month.

Example month·Where the value comes from site, country, brand, model, year, fuel, gearbox, condition, month or week.

site / site_excludestring · query string

Comma-separated source slugs to include or leave out. An unknown slug is a 400 naming the offender.

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

brand / modelstring · query string

Brand name, slug or brand_id, and model name or slug, matched exactly as on /api/archive/search. Giving brand adds a model facet.

Example bmw / 320d·Where the value comes from /api/brands -> brands[].slug, /api/models?brand=bmw -> models[].slug

countrystring · query string

ISO country code or europe.

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

fuel / gearboxstring · query string

Canonical fuel and gearbox groups.

Example Diesel·Where the value comes from /api/fuels -> fuels[], /api/gearboxes -> gearboxes[]

year_from / year_tointeger · query string

Registration-year range, inclusive.

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

production_year_from / production_year_tointeger · query string

Production-year range. Falls back to registration year where the source publishes no build year.

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

kilometers_from / kilometers_tointeger · query string

Mileage range in kilometres.

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

price_from / price_tointeger · query string

Public EUR price range.

Example 1000 / 30000·Where the value comes from EUR budget chosen by your user.

horsepower_from / horsepower_tointeger · query string

Power range in HP.

Example 150 / 300·Where the value comes from Power bounds chosen by your user.

engine_from / engine_tonumber · query string

Engine size in litres. 1.6 matches from 1550 cc; 2.0 matches up to 2049 cc.

Example 1.6 / 2.0·Where the value comes from Engine sizes chosen by your user.

damagedboolean · query string

true keeps only damaged or broken vehicles, false only undamaged ones.

Example false·Where the value comes from Your filter choice.

archived_from / archived_tostring · query string

Lots that ended on or after / on or before this date (YYYY-MM-DD).

Example 2026-07-01 / 2026-09-30·Where the value comes from Date range chosen by your user.

vinstring · query string

Exact full-VIN filter.

Example WBA8E9G50GNU12345·Where the value comes from A VIN you already have.

limitinteger · query string

Groups returned. Default 100, maximum 500.

Example 24·Where the value comes from How many groups you will show.

Example requests

Request

GET https://api.thecarapi.com/api/archive/statistics?brand=bmw&model=320d&group_by=month

GET https://api.thecarapi.com/api/archive/statistics?group_by=country&year_from=2019

Example response

json

{
  "success": true,
  "group_by": "month",
  "groups": [
    {
      "month": "2026-09",
      "count": 412,
      "priced_count": 401,
      "result_count": 140,
      "buy_now_count": 37,
      "close_median_eur": 18400,
      "close_p25_eur": 14200,
      "close_p75_eur": 22900,
      "close_mean_eur": 18950,
      "buy_now_median_eur": 21900,
      "mean_mileage_km": 98000,
      "mean_hp": 184,
      "damaged_share": 0.08
    }
  ],
  "notes": {
    "close_price": "the source's published result where it has one (result_count), else the last bid seen - not proof of a sale",
    "coverage": "archived lots plus lots that ended and are not archived yet"
  }
}

What you get back

groups[]object[]

Each group is keyed by its dimension (month: "2026-09", site: "openlane", ...) and carries count, priced_count, result_count (lots whose source published a result), buy_now_count, close_median_eur, close_p25_eur, close_p75_eur, close_mean_eur, buy_now_median_eur, mean_mileage_km, mean_hp and damaged_share (0–1). EUR and mean figures are whole numbers, null where nothing in the group had a value. month, week and year groups come back in chronological order, every other grouping biggest first.

notesobject

Plain-language caveats: what close_price means and which lots are covered.

GET

/api/archive/stats

Archive coverage per source

Requires the archive scope.

Example request

Request

GET https://api.thecarapi.com/api/archive/stats

Example response

json

{
  "success": true,
  "total": 0,
  "archived_from": null,
  "archived_to": null,
  "sources": [],
  "contract_version": "2026-10-05"
}