Ендпойнти

Фасети за филтри

Discover live filter values and counts. Every facet endpoint accepts the search filters, so a facet describes whatever slice of inventory you are looking at rather than the whole of it — each dimension ignoring only its own filter, so a user can switch brands without the option disappearing. Counts and the totals /api/search reports for the same filters cannot disagree. Facet responses cache for about 600 seconds, and a filter sidebar can read every flat dimension in one call with /api/facets.

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

GET

/api/types

Trim filter values for one brand and model

Изисква обхвата search scope.

Параметри

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.

Пример 4,4.5,5·Откъде идва стойността 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.

Пример uss,honda_tokyo·Откъде идва стойността 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.

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

Пример USF40,ZC6·Откъде идва стойността 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`.

Пример true·Откъде идва стойността Current API reference

buy_nowboolean · query string

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

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

Пример DE·Откъде идва стойността Current API reference

brandstring · query stringзадължителен

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

Пример bmw·Откъде идва стойността Current API reference

modelstring · query stringзадължителен

Model name from `/api/models`. Comma-separated values select several.

Пример 5-Series·Откъде идва стойността Current API reference

year_frominteger · query string

Lower bound on registration year, inclusive.

Пример 2018·Откъде идва стойността Current API reference

year_tointeger · query string

Upper bound on registration year, inclusive.

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

Пример 2018·Откъде идва стойността Current API reference

production_year_tointeger · query string

Upper bound on production year, inclusive.

Пример 2024·Откъде идва стойността Current API reference

fuelstring · query string

Canonical fuel group from `/api/fuels`.

Пример Diesel·Откъде идва стойността Current API reference

gearboxstring · query string

Canonical gearbox group from `/api/gearboxes`.

Пример Automatic·Откъде идва стойността Current API reference

kilometers_frominteger · query string

Lower bound on mileage in kilometres.

Пример 0·Откъде идва стойността Current API reference

kilometers_tointeger · query string

Upper bound on mileage in kilometres.

Пример 150000·Откъде идва стойността Current API reference

horsepower_frominteger · query string

Пример ·Откъде идва стойността Current API reference

horsepower_tointeger · query string

Пример ·Откъде идва стойността Current API reference

price_frominteger · query string

Lower bound on the public EUR price.

Пример 1000·Откъде идва стойността Current API reference

price_tointeger · query string

Upper bound on the public EUR price.

Пример 30000·Откъде идва стойността Current API reference

typestring · query string

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

Пример 520d·Откъде идва стойността Current API reference

vehicle_typestring · query string

Пример ·Откъде идва стойността Current API reference

body_stylestring · query string

Пример ·Откъде идва стойността Current API reference

ending_soonboolean · query string

`true` restricts to auctions ending within roughly two hours.

Пример true·Откъде идва стойността Current API reference

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.

Пример openlane,auto1·Откъде идва стойността Current API reference

site_excludestring · query string

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

Пример copart·Откъде идва стойността Current API reference

searchstring · query string

Substring filter on the facet value name.

Пример ·Откъде идва стойността Current API reference

orderingstring · query string

Пример ·Откъде идва стойността Current API reference

limitinteger · query string

Maximum facet values to return.

Пример 20·Откъде идва стойността Current API reference

steeringstring · query string

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.

Пример left·Откъде идва стойността Current API reference

Example request

Request

GET https://api.thecarapi.com/api/types?brand=bmw&model=320d

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

json

{
  "success": true,
  "types": [
    {
      "name": "Touring",
      "count": 12
    }
  ],
  "grouped": {"320d": [{"name": "Touring", "count": 12}]}
}

GET

/api/production-years

Available production years

Изисква обхвата search scope.

Параметри

auction_gradestring · query string

Пример 4,4.5,5·Откъде идва стойността Listing values or your application settings.

auction_housestring · query string

Пример uss,honda_tokyo·Откъде идва стойността Listing values or your application settings.

lot_numberstring · query string

Пример 80041·Откъде идва стойността Listing values or your application settings.

model_codestring · query string

Пример USF40,ZC6·Откъде идва стойността 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`.

Пример true·Откъде идва стойността Current API reference

buy_nowboolean · query string

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

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

Пример DE·Откъде идва стойността Current API reference

brandstring · query string

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

Пример bmw·Откъде идва стойността Current API reference

modelstring · query string

Model name or slug.

Пример 320d·Откъде идва стойността Current API reference

year_frominteger · query string

Lower bound on registration year, inclusive.

Пример 2018·Откъде идва стойността Current API reference

year_tointeger · query string

Upper bound on registration year, inclusive.

Пример 2024·Откъде идва стойността Current API reference

production_year_frominteger · query string

Пример 2018·Откъде идва стойността Current API reference

production_year_tointeger · query string

Upper bound on production year, inclusive.

Пример 2024·Откъде идва стойността Current API reference

fuelstring · query string

Canonical fuel group from `/api/fuels`.

Пример Diesel·Откъде идва стойността Current API reference

gearboxstring · query string

Canonical gearbox group from `/api/gearboxes`.

Пример Automatic·Откъде идва стойността Current API reference

kilometers_frominteger · query string

Lower bound on mileage in kilometres.

Пример 0·Откъде идва стойността Current API reference

kilometers_tointeger · query string

Upper bound on mileage in kilometres.

Пример 150000·Откъде идва стойността Current API reference

horsepower_frominteger · query string

Пример ·Откъде идва стойността Current API reference

horsepower_tointeger · query string

Пример ·Откъде идва стойността Current API reference

price_frominteger · query string

Lower bound on the public EUR price.

Пример 1000·Откъде идва стойността Current API reference

price_tointeger · query string

Upper bound on the public EUR price.

Пример 30000·Откъде идва стойността Current API reference

typestring · query string

Пример 520d·Откъде идва стойността Current API reference

vehicle_typestring · query string

Пример ·Откъде идва стойността Current API reference

body_stylestring · query string

Пример ·Откъде идва стойността Current API reference

ending_soonboolean · query string

`true` restricts to auctions ending within roughly two hours.

Пример true·Откъде идва стойността Current API reference

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.

Пример openlane,auto1·Откъде идва стойността Current API reference

site_excludestring · query string

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

Пример copart·Откъде идва стойността Current API reference

steeringstring · query string

Пример left·Откъде идва стойността Current API reference

Example request

Request

GET https://api.thecarapi.com/api/production-years

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

json

{
  "success": true,
  "production_years": [
    2023,
    2022
  ],
  "production_year_counts": [
    {
      "value": 2023,
      "count": 12
    }
  ]
}

GET

/api/facets

Every facet dimension of a filter sidebar in one request.

Изисква обхвата search scope.

Параметри

auction_gradestring · query string

Пример 4,4.5,5·Откъде идва стойността Listing values or your application settings.

auction_housestring · query string

Пример uss,honda_tokyo·Откъде идва стойността Listing values or your application settings.

lot_numberstring · query string

Пример 80041·Откъде идва стойността Listing values or your application settings.

model_codestring · query string

Пример USF40,ZC6·Откъде идва стойността Listing values or your application settings.

fieldsstring · query string

Comma-separated subset of brands, years, production_years, fuels, countries, gearboxes, sites, plus the opt-in models and types. Defaults to all but the opt-in two. models needs brand, types needs brand and model, exactly as /api/models and /api/types do; without them the field is reported under errors. That makes a full sidebar one call: ?brand=BMW&model=3-Series&fields=brands,models,types,years,fuels.

Пример brands,fuels,gearboxes·Откъде идва стойността The dimensions your sidebar actually renders.

auction_gradestring · query string

Пример 4,4.5,5·Откъде идва стойността Listing values or your application settings.

auction_housestring · query string

Пример uss,honda_tokyo·Откъде идва стойността Listing values or your application settings.

lot_numberstring · query string

Пример 80041·Откъде идва стойността Listing values or your application settings.

model_codestring · query string

Пример USF40,ZC6·Откъде идва стойността Listing values or your application settings.

production_year_from / production_year_tointeger · query string

Production-year bounds. Falls back to registration year when the source provides no production year.

Пример 2019 / 2024·Откъде идва стойността /api/production-years

typestring · query string

Trim/type filter, distinct from vehicle_type and body_style. Accepts multiple comma-separated values; unclassified trims are retained.

Пример Touring·Откъде идва стойността /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

Name, slug, or brand_id, exactly as on /api/search.

Пример bmw·Откъде идва стойността /api/brands -> brands[].slug (or id/name)

year_from / year_tointeger · query string

Registration-year range. Accepted and ignored by /api/years itself, which is the dimension they would narrow.

Пример 2018 / 2024·Откъде идва стойността /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

Пример Diesel·Откъде идва стойността /api/fuels -> fuels[], /api/gearboxes -> gearboxes[]

countrystring · query string

ISO country code or europe. Accepted and ignored by /api/sites and /load-models.

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

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

horsepower_from / horsepower_tointeger · query string

Power range in HP.

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

price_from / price_tointeger · query string

Public EUR price range. price_to=5000 on /api/brands returns each brand count under EUR 5,000.

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Пример cars·Откъде идва стойността As on /api/search.

steeringenum · query string

Restrict to left- or right-hand-drive vehicles. Slower than an unfiltered facet call, because it is computed live rather than read from the precomputed facet table.

damagedboolean · query string

Restrict to damaged or broken vehicles.

Пример true·Откъде идва стойността Your filter choice.

buy_nowboolean · query string

Restrict to Buy-Now inventory.

Пример true·Откъде идва стойността Your filter choice.

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Пример true·Откъде идва стойността Your filter choice.

Example requests

Request

GET https://api.thecarapi.com/api/facets?fields=brands,fuels,gearboxes&country=DE

GET https://api.thecarapi.com/api/facets?fields=brands,years,sites&damaged=true

GET https://api.thecarapi.com/api/facets?brand=bmw&model=320d&fields=brands,models,types,years,fuels

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

json

{
  "success": true,
  "brands": [
    {
      "id": 12,
      "name": "BMW",
      "slug": "bmw",
      "count": 3266
    }
  ],
  "fuels": [
    "Diesel",
    "Petrol"
  ],
  "gearboxes": [
    "Automatic",
    "Manual"
  ]
}

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

brands / years / production_years / fuels / countries / gearboxes / sites / models / typesarray

Each field is its own endpoint’s payload merged verbatim (models and types only when named in fields) — countries still ships country_details alongside it, and no field gains or loses counts by being requested here.

errorsobject

Present only when a dimension could not be served: { field: reason }. Every other field is still returned, so one slow dimension cannot blank a filter sidebar.

GET

/api/brands

List brands with round-trippable slugs and live inventory counts.

Изисква обхвата search scope.

Параметри

auction_gradestring · query string

Пример 4,4.5,5·Откъде идва стойността Listing values or your application settings.

auction_housestring · query string

Пример uss,honda_tokyo·Откъде идва стойността Listing values or your application settings.

lot_numberstring · query string

Пример 80041·Откъде идва стойността Listing values or your application settings.

model_codestring · query string

Пример USF40,ZC6·Откъде идва стойността Listing values or your application settings.

auction_gradestring · query string

Пример 4,4.5,5·Откъде идва стойността Listing values or your application settings.

auction_housestring · query string

Пример uss,honda_tokyo·Откъде идва стойността Listing values or your application settings.

lot_numberstring · query string

Пример 80041·Откъде идва стойността Listing values or your application settings.

model_codestring · query string

Пример USF40,ZC6·Откъде идва стойността Listing values or your application settings.

production_year_from / production_year_tointeger · query string

Production-year bounds. Falls back to registration year when the source provides no production year.

Пример 2019 / 2024·Откъде идва стойността /api/production-years

typestring · query string

Trim/type filter, distinct from vehicle_type and body_style. Accepts multiple comma-separated values; unclassified trims are retained.

Пример Touring·Откъде идва стойността /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

Name, slug, or brand_id, exactly as on /api/search.

Пример bmw·Откъде идва стойността /api/brands -> brands[].slug (or id/name)

year_from / year_tointeger · query string

Registration-year range. Accepted and ignored by /api/years itself, which is the dimension they would narrow.

Пример 2018 / 2024·Откъде идва стойността /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

Пример Diesel·Откъде идва стойността /api/fuels -> fuels[], /api/gearboxes -> gearboxes[]

countrystring · query string

ISO country code or europe. Accepted and ignored by /api/sites and /load-models.

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

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

horsepower_from / horsepower_tointeger · query string

Power range in HP.

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

price_from / price_tointeger · query string

Public EUR price range. price_to=5000 on /api/brands returns each brand count under EUR 5,000.

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Пример cars·Откъде идва стойността As on /api/search.

steeringenum · query string

Restrict to left- or right-hand-drive vehicles. Slower than an unfiltered facet call, because it is computed live rather than read from the precomputed facet table.

damagedboolean · query string

Restrict to damaged or broken vehicles.

Пример true·Откъде идва стойността Your filter choice.

buy_nowboolean · query string

Restrict to Buy-Now inventory.

Пример true·Откъде идва стойността Your filter choice.

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Пример true·Откъде идва стойността Your filter choice.

searchstring · query string

Substring filter on brand name.

Пример bm·Откъде идва стойността Free text entered by your user.

orderingenum · query string

name, -name, count, or -count. An unrecognised value falls back to name rather than erroring.

Пример -count·Откъде идва стойността Choose name, -name, count, or -count.

limitinteger · query string

Maximum number of values. No default — the full brand list is returned unless you cap it, which is what a filter sidebar wants.

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

Example requests

Request

GET https://api.thecarapi.com/api/brands?search=bm&ordering=-count&limit=20

GET https://api.thecarapi.com/api/brands?country=DE&damaged=true

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

json

{
  "success": true,
  "brands": [
    {
      "id": 12,
      "name": "BMW",
      "slug": "bmw",
      "count": 1543
    }
  ]
}

GET

/api/models

List models for one brand with live inventory counts.

Изисква обхвата search scope.

Параметри

auction_gradestring · query string

Пример 4,4.5,5·Откъде идва стойността Listing values or your application settings.

auction_housestring · query string

Пример uss,honda_tokyo·Откъде идва стойността Listing values or your application settings.

lot_numberstring · query string

Пример 80041·Откъде идва стойността Listing values or your application settings.

model_codestring · query string

Пример USF40,ZC6·Откъде идва стойността Listing values or your application settings.

brandstring | integer · query stringзадължителен

Brand name, slug, or brand_id.

Пример bmw·Откъде идва стойността /api/brands -> brands[].slug (or id/name)

auction_gradestring · query string

Пример 4,4.5,5·Откъде идва стойността Listing values or your application settings.

auction_housestring · query string

Пример uss,honda_tokyo·Откъде идва стойността Listing values or your application settings.

lot_numberstring · query string

Пример 80041·Откъде идва стойността Listing values or your application settings.

model_codestring · query string

Пример USF40,ZC6·Откъде идва стойността Listing values or your application settings.

production_year_from / production_year_tointeger · query string

Production-year bounds. Falls back to registration year when the source provides no production year.

Пример 2019 / 2024·Откъде идва стойността /api/production-years

typestring · query string

Trim/type filter, distinct from vehicle_type and body_style. Accepts multiple comma-separated values; unclassified trims are retained.

Пример Touring·Откъде идва стойността /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

Name, slug, or brand_id, exactly as on /api/search.

Пример bmw·Откъде идва стойността /api/brands -> brands[].slug (or id/name)

year_from / year_tointeger · query string

Registration-year range. Accepted and ignored by /api/years itself, which is the dimension they would narrow.

Пример 2018 / 2024·Откъде идва стойността /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

Пример Diesel·Откъде идва стойността /api/fuels -> fuels[], /api/gearboxes -> gearboxes[]

countrystring · query string

ISO country code or europe. Accepted and ignored by /api/sites and /load-models.

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

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

horsepower_from / horsepower_tointeger · query string

Power range in HP.

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

price_from / price_tointeger · query string

Public EUR price range. price_to=5000 on /api/brands returns each brand count under EUR 5,000.

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Пример cars·Откъде идва стойността As on /api/search.

steeringenum · query string

Restrict to left- or right-hand-drive vehicles. Slower than an unfiltered facet call, because it is computed live rather than read from the precomputed facet table.

damagedboolean · query string

Restrict to damaged or broken vehicles.

Пример true·Откъде идва стойността Your filter choice.

buy_nowboolean · query string

Restrict to Buy-Now inventory.

Пример true·Откъде идва стойността Your filter choice.

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Пример true·Откъде идва стойността Your filter choice.

searchstring · query string

Substring filter on model name.

Пример x·Откъде идва стойността Free text entered by your user.

orderingenum · query string

name, -name, count, or -count. An unrecognised value falls back to name rather than erroring.

Пример -count·Откъде идва стойността Choose name, -name, count, or -count.

limitinteger · query string

Maximum number of values. No default — the full model list for the brand is returned unless you cap it.

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

Example requests

Request

GET https://api.thecarapi.com/api/models?brand=bmw&ordering=-count

GET https://api.thecarapi.com/api/models?brand=12&search=x&country=DE

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

json

{
  "success": true,
  "models": [
    {
      "name": "320d",
      "slug": "320d",
      "count": 210
    }
  ]
}

GET

/api/years

List registration years available in current inventory.

Изисква обхвата search scope.

Параметри

auction_gradestring · query string

Пример 4,4.5,5·Откъде идва стойността Listing values or your application settings.

auction_housestring · query string

Пример uss,honda_tokyo·Откъде идва стойността Listing values or your application settings.

lot_numberstring · query string

Пример 80041·Откъде идва стойността Listing values or your application settings.

model_codestring · query string

Пример USF40,ZC6·Откъде идва стойността Listing values or your application settings.

production_year_from / production_year_tointeger · query string

Production-year bounds. Falls back to registration year when the source provides no production year.

Пример 2019 / 2024·Откъде идва стойността /api/production-years

typestring · query string

Trim/type filter, distinct from vehicle_type and body_style. Accepts multiple comma-separated values; unclassified trims are retained.

Пример Touring·Откъде идва стойността /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

Name, slug, or brand_id, exactly as on /api/search.

Пример bmw·Откъде идва стойността /api/brands -> brands[].slug (or id/name)

year_from / year_tointeger · query string

Registration-year range. Accepted and ignored by /api/years itself, which is the dimension they would narrow.

Пример 2018 / 2024·Откъде идва стойността /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

Пример Diesel·Откъде идва стойността /api/fuels -> fuels[], /api/gearboxes -> gearboxes[]

countrystring · query string

ISO country code or europe. Accepted and ignored by /api/sites and /load-models.

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

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

horsepower_from / horsepower_tointeger · query string

Power range in HP.

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

price_from / price_tointeger · query string

Public EUR price range. price_to=5000 on /api/brands returns each brand count under EUR 5,000.

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Пример cars·Откъде идва стойността As on /api/search.

steeringenum · query string

Restrict to left- or right-hand-drive vehicles. Slower than an unfiltered facet call, because it is computed live rather than read from the precomputed facet table.

damagedboolean · query string

Restrict to damaged or broken vehicles.

Пример true·Откъде идва стойността Your filter choice.

buy_nowboolean · query string

Restrict to Buy-Now inventory.

Пример true·Откъде идва стойността Your filter choice.

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Пример true·Откъде идва стойността Your filter choice.

Example requests

Request

GET https://api.thecarapi.com/api/years?country=DE

GET https://api.thecarapi.com/api/years?damaged=true&buy_now=true

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

json

{
  "success": true,
  "years": [
    2024,
    2023,
    2022,
    2021
  ],
  "year_counts": [
    {
      "value": 2024,
      "count": 512
    },
    {
      "value": 2023,
      "count": 4127
    },
    {
      "value": 2022,
      "count": 3890
    },
    {
      "value": 2021,
      "count": 3544
    }
  ]
}

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

yearsinteger[]

Registration years present in the filtered inventory, newest first.

year_counts{value, count}[]

Mirrors years in the same order. Each count is the offers for that registration year under the request other filters.

GET

/api/fuels

List canonical fuel groups available in current inventory.

Изисква обхвата search scope.

Параметри

auction_gradestring · query string

Пример 4,4.5,5·Откъде идва стойността Listing values or your application settings.

auction_housestring · query string

Пример uss,honda_tokyo·Откъде идва стойността Listing values or your application settings.

lot_numberstring · query string

Пример 80041·Откъде идва стойността Listing values or your application settings.

model_codestring · query string

Пример USF40,ZC6·Откъде идва стойността Listing values or your application settings.

production_year_from / production_year_tointeger · query string

Production-year bounds. Falls back to registration year when the source provides no production year.

Пример 2019 / 2024·Откъде идва стойността /api/production-years

typestring · query string

Trim/type filter, distinct from vehicle_type and body_style. Accepts multiple comma-separated values; unclassified trims are retained.

Пример Touring·Откъде идва стойността /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

Name, slug, or brand_id, exactly as on /api/search.

Пример bmw·Откъде идва стойността /api/brands -> brands[].slug (or id/name)

year_from / year_tointeger · query string

Registration-year range. Accepted and ignored by /api/years itself, which is the dimension they would narrow.

Пример 2018 / 2024·Откъде идва стойността /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

Пример Diesel·Откъде идва стойността /api/fuels -> fuels[], /api/gearboxes -> gearboxes[]

countrystring · query string

ISO country code or europe. Accepted and ignored by /api/sites and /load-models.

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

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

horsepower_from / horsepower_tointeger · query string

Power range in HP.

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

price_from / price_tointeger · query string

Public EUR price range. price_to=5000 on /api/brands returns each brand count under EUR 5,000.

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Пример cars·Откъде идва стойността As on /api/search.

steeringenum · query string

Restrict to left- or right-hand-drive vehicles. Slower than an unfiltered facet call, because it is computed live rather than read from the precomputed facet table.

damagedboolean · query string

Restrict to damaged or broken vehicles.

Пример true·Откъде идва стойността Your filter choice.

buy_nowboolean · query string

Restrict to Buy-Now inventory.

Пример true·Откъде идва стойността Your filter choice.

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Пример true·Откъде идва стойността Your filter choice.

Example requests

Request

GET https://api.thecarapi.com/api/fuels?country=DE

GET https://api.thecarapi.com/api/fuels?buy_now=true

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

json

{
  "success": true,
  "fuels": [
    "Diesel",
    "Electric",
    "Hybrid",
    "Mild Hybrid",
    "Petrol",
    "Plug-in Hybrid"
  ],
  "fuel_counts": [
    {
      "value": "Diesel",
      "count": 18342
    },
    {
      "value": "Electric",
      "count": 903
    },
    {
      "value": "Hybrid",
      "count": 2211
    },
    {
      "value": "Mild Hybrid",
      "count": 5107
    },
    {
      "value": "Petrol",
      "count": 24980
    },
    {
      "value": "Plug-in Hybrid",
      "count": 1489
    }
  ]
}

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

fuelsstring[]

Canonical fuel groups present in the filtered inventory, alphabetical.

fuel_counts{value, count}[]

Mirrors fuels in the same order.

GET

/api/gearboxes

List canonical gearbox groups available in current inventory.

Изисква обхвата search scope.

Параметри

auction_gradestring · query string

Пример 4,4.5,5·Откъде идва стойността Listing values or your application settings.

auction_housestring · query string

Пример uss,honda_tokyo·Откъде идва стойността Listing values or your application settings.

lot_numberstring · query string

Пример 80041·Откъде идва стойността Listing values or your application settings.

model_codestring · query string

Пример USF40,ZC6·Откъде идва стойността Listing values or your application settings.

production_year_from / production_year_tointeger · query string

Production-year bounds. Falls back to registration year when the source provides no production year.

Пример 2019 / 2024·Откъде идва стойността /api/production-years

typestring · query string

Trim/type filter, distinct from vehicle_type and body_style. Accepts multiple comma-separated values; unclassified trims are retained.

Пример Touring·Откъде идва стойността /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

Name, slug, or brand_id, exactly as on /api/search.

Пример bmw·Откъде идва стойността /api/brands -> brands[].slug (or id/name)

year_from / year_tointeger · query string

Registration-year range. Accepted and ignored by /api/years itself, which is the dimension they would narrow.

Пример 2018 / 2024·Откъде идва стойността /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

Пример Diesel·Откъде идва стойността /api/fuels -> fuels[], /api/gearboxes -> gearboxes[]

countrystring · query string

ISO country code or europe. Accepted and ignored by /api/sites and /load-models.

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

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

horsepower_from / horsepower_tointeger · query string

Power range in HP.

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

price_from / price_tointeger · query string

Public EUR price range. price_to=5000 on /api/brands returns each brand count under EUR 5,000.

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Пример cars·Откъде идва стойността As on /api/search.

steeringenum · query string

Restrict to left- or right-hand-drive vehicles. Slower than an unfiltered facet call, because it is computed live rather than read from the precomputed facet table.

damagedboolean · query string

Restrict to damaged or broken vehicles.

Пример true·Откъде идва стойността Your filter choice.

buy_nowboolean · query string

Restrict to Buy-Now inventory.

Пример true·Откъде идва стойността Your filter choice.

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Пример true·Откъде идва стойността Your filter choice.

Example requests

Request

GET https://api.thecarapi.com/api/gearboxes?country=KR

GET https://api.thecarapi.com/api/gearboxes?damaged=true

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

json

{
  "success": true,
  "gearboxes": [
    "Automatic",
    "Manual"
  ],
  "gearbox_counts": [
    {
      "value": "Automatic",
      "count": 22190
    },
    {
      "value": "Manual",
      "count": 15432
    }
  ]
}

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

gearboxesstring[]

Canonical gearbox groups present in the filtered inventory.

gearbox_counts{value, count}[]

Mirrors gearboxes in the same order.

GET

/api/countries

List vehicle-location countries and display names.

Изисква обхвата search scope.

Параметри

auction_gradestring · query string

Пример 4,4.5,5·Откъде идва стойността Listing values or your application settings.

auction_housestring · query string

Пример uss,honda_tokyo·Откъде идва стойността Listing values or your application settings.

lot_numberstring · query string

Пример 80041·Откъде идва стойността Listing values or your application settings.

model_codestring · query string

Пример USF40,ZC6·Откъде идва стойността Listing values or your application settings.

production_year_from / production_year_tointeger · query string

Production-year bounds. Falls back to registration year when the source provides no production year.

Пример 2019 / 2024·Откъде идва стойността /api/production-years

typestring · query string

Trim/type filter, distinct from vehicle_type and body_style. Accepts multiple comma-separated values; unclassified trims are retained.

Пример Touring·Откъде идва стойността /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

Name, slug, or brand_id, exactly as on /api/search.

Пример bmw·Откъде идва стойността /api/brands -> brands[].slug (or id/name)

year_from / year_tointeger · query string

Registration-year range. Accepted and ignored by /api/years itself, which is the dimension they would narrow.

Пример 2018 / 2024·Откъде идва стойността /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

Пример Diesel·Откъде идва стойността /api/fuels -> fuels[], /api/gearboxes -> gearboxes[]

countrystring · query string

ISO country code or europe. Accepted and ignored by /api/sites and /load-models.

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

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

horsepower_from / horsepower_tointeger · query string

Power range in HP.

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

price_from / price_tointeger · query string

Public EUR price range. price_to=5000 on /api/brands returns each brand count under EUR 5,000.

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Пример cars·Откъде идва стойността As on /api/search.

steeringenum · query string

Restrict to left- or right-hand-drive vehicles. Slower than an unfiltered facet call, because it is computed live rather than read from the precomputed facet table.

damagedboolean · query string

Restrict to damaged or broken vehicles.

Пример true·Откъде идва стойността Your filter choice.

buy_nowboolean · query string

Restrict to Buy-Now inventory.

Пример true·Откъде идва стойността Your filter choice.

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Пример true·Откъде идва стойността Your filter choice.

Example requests

Request

GET https://api.thecarapi.com/api/countries?buy_now=true

GET https://api.thecarapi.com/api/countries?damaged=true

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

json

{
  "success": true,
  "countries": [
    "DE",
    "JP",
    "KR",
    "NL"
  ],
  "country_details": [
    {
      "code": "DE",
      "name": "Germany"
    },
    {
      "code": "JP",
      "name": "Japan"
    },
    {
      "code": "KR",
      "name": "South Korea"
    },
    {
      "code": "NL",
      "name": "Netherlands"
    }
  ],
  "country_counts": [
    {
      "value": "DE",
      "count": 9871
    },
    {
      "value": "JP",
      "count": 14203
    },
    {
      "value": "KR",
      "count": 8455
    },
    {
      "value": "NL",
      "count": 3120
    }
  ]
}

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

countriesstring[]

ISO country codes present in the filtered inventory.

country_details{code, name}[]

The same codes with display names, for rendering a picker.

country_counts{value, count}[]

Keyed by canonical ISO code (UK folds into GB), in the same order as countries.

GET

/api/sites

List auction source slugs with live inventory counts.

Изисква обхвата search scope.

Параметри

auction_gradestring · query string

Пример 4,4.5,5·Откъде идва стойността Listing values or your application settings.

auction_housestring · query string

Пример uss,honda_tokyo·Откъде идва стойността Listing values or your application settings.

lot_numberstring · query string

Пример 80041·Откъде идва стойността Listing values or your application settings.

model_codestring · query string

Пример USF40,ZC6·Откъде идва стойността Listing values or your application settings.

production_year_from / production_year_tointeger · query string

Production-year bounds. Falls back to registration year when the source provides no production year.

Пример 2019 / 2024·Откъде идва стойността /api/production-years

typestring · query string

Trim/type filter, distinct from vehicle_type and body_style. Accepts multiple comma-separated values; unclassified trims are retained.

Пример Touring·Откъде идва стойността /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

Name, slug, or brand_id, exactly as on /api/search.

Пример bmw·Откъде идва стойността /api/brands -> brands[].slug (or id/name)

year_from / year_tointeger · query string

Registration-year range. Accepted and ignored by /api/years itself, which is the dimension they would narrow.

Пример 2018 / 2024·Откъде идва стойността /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

Пример Diesel·Откъде идва стойността /api/fuels -> fuels[], /api/gearboxes -> gearboxes[]

countrystring · query string

ISO country code or europe. Accepted and ignored by /api/sites and /load-models.

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

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

horsepower_from / horsepower_tointeger · query string

Power range in HP.

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

price_from / price_tointeger · query string

Public EUR price range. price_to=5000 on /api/brands returns each brand count under EUR 5,000.

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Пример cars·Откъде идва стойността As on /api/search.

steeringenum · query string

Restrict to left- or right-hand-drive vehicles. Slower than an unfiltered facet call, because it is computed live rather than read from the precomputed facet table.

damagedboolean · query string

Restrict to damaged or broken vehicles.

Пример true·Откъде идва стойността Your filter choice.

buy_nowboolean · query string

Restrict to Buy-Now inventory.

Пример true·Откъде идва стойността Your filter choice.

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Пример true·Откъде идва стойността Your filter choice.

Example requests

Request

GET https://api.thecarapi.com/api/sites?buy_now=true

GET https://api.thecarapi.com/api/sites?damaged=true

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

json

{
  "success": true,
  "sites": [
    {
      "id": 1,
      "name": "encar",
      "count": 9021
    },
    {
      "id": 2,
      "name": "openlane",
      "count": 4110
    },
    {
      "id": 4,
      "name": "japan",
      "count": 1642
    }
  ]
}

GET

/load-models

Return the complete model catalog grouped by brand.

Изисква обхвата search scope.

Параметри

auction_gradestring · query string

Пример 4,4.5,5·Откъде идва стойността Listing values or your application settings.

auction_housestring · query string

Пример uss,honda_tokyo·Откъде идва стойността Listing values or your application settings.

lot_numberstring · query string

Пример 80041·Откъде идва стойността Listing values or your application settings.

model_codestring · query string

Пример USF40,ZC6·Откъде идва стойността Listing values or your application settings.

production_year_from / production_year_tointeger · query string

Production-year bounds. Falls back to registration year when the source provides no production year.

Пример 2019 / 2024·Откъде идва стойността /api/production-years

typestring · query string

Trim/type filter, distinct from vehicle_type and body_style. Accepts multiple comma-separated values; unclassified trims are retained.

Пример Touring·Откъде идва стойността /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

Name, slug, or brand_id, exactly as on /api/search.

Пример bmw·Откъде идва стойността /api/brands -> brands[].slug (or id/name)

year_from / year_tointeger · query string

Registration-year range. Accepted and ignored by /api/years itself, which is the dimension they would narrow.

Пример 2018 / 2024·Откъде идва стойността /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

Пример Diesel·Откъде идва стойността /api/fuels -> fuels[], /api/gearboxes -> gearboxes[]

countrystring · query string

ISO country code or europe. Accepted and ignored by /api/sites and /load-models.

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

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

horsepower_from / horsepower_tointeger · query string

Power range in HP.

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

price_from / price_tointeger · query string

Public EUR price range. price_to=5000 on /api/brands returns each brand count under EUR 5,000.

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Пример cars·Откъде идва стойността As on /api/search.

steeringenum · query string

Restrict to left- or right-hand-drive vehicles. Slower than an unfiltered facet call, because it is computed live rather than read from the precomputed facet table.

damagedboolean · query string

Restrict to damaged or broken vehicles.

Пример true·Откъде идва стойността Your filter choice.

buy_nowboolean · query string

Restrict to Buy-Now inventory.

Пример true·Откъде идва стойността Your filter choice.

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Пример true·Откъде идва стойността Your filter choice.

Example requests

Request

GET https://api.thecarapi.com/load-models?country=DE

GET https://api.thecarapi.com/load-models?buy_now=true&damaged=false

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

json

{
  "BMW": [
    {
      "text": "320d"
    },
    {
      "text": "X5"
    }
  ],
  "Volvo": [
    {
      "text": "XC60"
    }
  ]
}