Endpoints

Filter facets

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.

GET

/api/types

Trim filter values for one brand and model

Requires the search scope.

Parameters

damagedboolean · query string

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

Example true·Where the value comes from Current API reference

buy_nowboolean · query string

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

Example true·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

brandstring · query stringrequired

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

Example bmw·Where the value comes from Current API reference

modelstring · query stringrequired

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

Example 5-Series·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

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

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

horsepower_frominteger · query string

Example ·Where the value comes from Current API reference

horsepower_tointeger · query string

Example ·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

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.

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

vehicle_typestring · query string

Example ·Where the value comes from Current API reference

body_stylestring · query string

Example ·Where the value comes from Current API reference

ending_soonboolean · query string

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

Example true·Where the value comes from 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.

Example openlane,ecarstrade·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

searchstring · query string

Substring filter on the facet value name.

Example ·Where the value comes from Current API reference

orderingstring · query string

Example ·Where the value comes from Current API reference

limitinteger · query string

Maximum facet values to return.

Example 20·Where the value comes from 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.

Example left·Where the value comes from Current API reference

Example request

Request

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

Example response

json

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

GET

/api/production-years

Available production years

Requires the search scope.

Parameters

damagedboolean · query string

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

Example true·Where the value comes from Current API reference

buy_nowboolean · query string

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

Example true·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

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

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

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

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

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

horsepower_frominteger · query string

Example ·Where the value comes from Current API reference

horsepower_tointeger · query string

Example ·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

typestring · query string

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

vehicle_typestring · query string

Example ·Where the value comes from Current API reference

body_stylestring · query string

Example ·Where the value comes from Current API reference

ending_soonboolean · query string

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

Example true·Where the value comes from 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.

Example openlane,ecarstrade·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

steeringstring · query string

Example left·Where the value comes from Current API reference

Example request

Request

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

Example response

json

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

GET

/api/facets

Every flat facet dimension in one request instead of seven.

Requires the search scope.

Parameters

fieldsstring · query string

Comma-separated subset of brands, years, production_years, fuels, countries, gearboxes, sites. Defaults to all of them. models and types are scoped separately; use /api/models and /api/types.

Example brands,fuels,gearboxes·Where the value comes from The dimensions your sidebar actually renders.

production_year_from / production_year_tointeger · query string

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

Example 2019 / 2024·Where the value comes from /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.

Example Touring·Where the value comes from /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

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

Example bmw·Where the value comes from /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.

Example 2018 / 2024·Where the value comes from /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

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

countrystring · query string

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

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

Example 0 / 150000·Where the value comes from Mileage bounds 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.

price_from / price_tointeger · query string

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

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Example cars·Where the value comes from 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.

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

buy_nowboolean · query string

Restrict to Buy-Now inventory.

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

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Example true·Where the value comes from 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

Example response

json

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

What you get back

brands / years / production_years / fuels / countries / gearboxes / sitesarray

Each field is its own endpoint’s payload merged verbatim — 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.

Requires the search scope.

Parameters

production_year_from / production_year_tointeger · query string

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

Example 2019 / 2024·Where the value comes from /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.

Example Touring·Where the value comes from /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

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

Example bmw·Where the value comes from /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.

Example 2018 / 2024·Where the value comes from /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

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

countrystring · query string

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

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

Example 0 / 150000·Where the value comes from Mileage bounds 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.

price_from / price_tointeger · query string

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

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Example cars·Where the value comes from 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.

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

buy_nowboolean · query string

Restrict to Buy-Now inventory.

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

ending_soonboolean · query string

Restrict to lots ending within about two hours.

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

searchstring · query string

Substring filter on brand name.

Example bm·Where the value comes from Free text entered by your user.

orderingenum · query string

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

Example -count·Where the value comes from 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.

Example 20·Where the value comes from 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

Example response

json

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

GET

/api/models

List models for one brand with live inventory counts.

Requires the search scope.

Parameters

brandstring | integer · query stringrequired

Brand name, slug, or brand_id.

Example bmw·Where the value comes from /api/brands -> brands[].slug (or id/name)

production_year_from / production_year_tointeger · query string

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

Example 2019 / 2024·Where the value comes from /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.

Example Touring·Where the value comes from /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

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

Example bmw·Where the value comes from /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.

Example 2018 / 2024·Where the value comes from /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

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

countrystring · query string

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

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

Example 0 / 150000·Where the value comes from Mileage bounds 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.

price_from / price_tointeger · query string

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

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Example cars·Where the value comes from 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.

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

buy_nowboolean · query string

Restrict to Buy-Now inventory.

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

ending_soonboolean · query string

Restrict to lots ending within about two hours.

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

searchstring · query string

Substring filter on model name.

Example x·Where the value comes from Free text entered by your user.

orderingenum · query string

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

Example -count·Where the value comes from 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.

Example 20·Where the value comes from 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

Example response

json

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

GET

/api/years

List registration years available in current inventory.

Requires the search scope.

Parameters

production_year_from / production_year_tointeger · query string

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

Example 2019 / 2024·Where the value comes from /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.

Example Touring·Where the value comes from /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

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

Example bmw·Where the value comes from /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.

Example 2018 / 2024·Where the value comes from /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

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

countrystring · query string

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

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

Example 0 / 150000·Where the value comes from Mileage bounds 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.

price_from / price_tointeger · query string

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

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Example cars·Where the value comes from 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.

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

buy_nowboolean · query string

Restrict to Buy-Now inventory.

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

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Example true·Where the value comes from 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

Example response

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
    }
  ]
}

What you get back

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.

Requires the search scope.

Parameters

production_year_from / production_year_tointeger · query string

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

Example 2019 / 2024·Where the value comes from /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.

Example Touring·Where the value comes from /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

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

Example bmw·Where the value comes from /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.

Example 2018 / 2024·Where the value comes from /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

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

countrystring · query string

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

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

Example 0 / 150000·Where the value comes from Mileage bounds 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.

price_from / price_tointeger · query string

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

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Example cars·Where the value comes from 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.

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

buy_nowboolean · query string

Restrict to Buy-Now inventory.

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

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Example true·Where the value comes from 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

Example response

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
    }
  ]
}

What you get back

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.

Requires the search scope.

Parameters

production_year_from / production_year_tointeger · query string

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

Example 2019 / 2024·Where the value comes from /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.

Example Touring·Where the value comes from /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

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

Example bmw·Where the value comes from /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.

Example 2018 / 2024·Where the value comes from /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

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

countrystring · query string

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

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

Example 0 / 150000·Where the value comes from Mileage bounds 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.

price_from / price_tointeger · query string

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

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Example cars·Where the value comes from 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.

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

buy_nowboolean · query string

Restrict to Buy-Now inventory.

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

ending_soonboolean · query string

Restrict to lots ending within about two hours.

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

Example requests

Request

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

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

Example response

json

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

What you get back

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.

Requires the search scope.

Parameters

production_year_from / production_year_tointeger · query string

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

Example 2019 / 2024·Where the value comes from /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.

Example Touring·Where the value comes from /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

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

Example bmw·Where the value comes from /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.

Example 2018 / 2024·Where the value comes from /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

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

countrystring · query string

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

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

Example 0 / 150000·Where the value comes from Mileage bounds 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.

price_from / price_tointeger · query string

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

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Example cars·Where the value comes from 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.

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

buy_nowboolean · query string

Restrict to Buy-Now inventory.

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

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Example true·Where the value comes from 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

Example response

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
    }
  ]
}

What you get back

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.

Requires the search scope.

Parameters

production_year_from / production_year_tointeger · query string

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

Example 2019 / 2024·Where the value comes from /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.

Example Touring·Where the value comes from /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

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

Example bmw·Where the value comes from /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.

Example 2018 / 2024·Where the value comes from /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

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

countrystring · query string

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

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

Example 0 / 150000·Where the value comes from Mileage bounds 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.

price_from / price_tointeger · query string

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

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Example cars·Where the value comes from 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.

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

buy_nowboolean · query string

Restrict to Buy-Now inventory.

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

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Example true·Where the value comes from 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

Example response

json

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

GET

/load-models

Return the complete model catalog grouped by brand.

Requires the search scope.

Parameters

production_year_from / production_year_tointeger · query string

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

Example 2019 / 2024·Where the value comes from /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.

Example Touring·Where the value comes from /api/types?brand=bmw&model=320d

brand / modelstring | integer · query string

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

Example bmw·Where the value comes from /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.

Example 2018 / 2024·Where the value comes from /api/years -> years[]

fuel / gearboxstring · query string

Canonical group, matched whole.

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

countrystring · query string

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

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

site / site_excludestring · query string

Comma-separated source slugs to include or leave out.

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

kilometers_from / kilometers_tointeger · query string

Mileage range.

Example 0 / 150000·Where the value comes from Mileage bounds 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.

price_from / price_tointeger · query string

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

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

vehicle_type / body_stylestring · query string

Vehicle-type and body-style filters.

Example cars·Where the value comes from 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.

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

buy_nowboolean · query string

Restrict to Buy-Now inventory.

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

ending_soonboolean · query string

Restrict to lots ending within about two hours.

Example true·Where the value comes from 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

Example response

json

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