Filter facets — API Reference

GET

/api/facets

Every flat facet dimension in one request instead of six.

Requires the search scope.

Parameters

fieldsstring · query string

Comma-separated subset of brands, years, fuels, countries, gearboxes, sites. Defaults to all of them. models is not available here — it is brand-scoped and stays at /api/models.

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

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.

countrystring · query string

ISO country code or europe.

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

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.

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

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 / 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

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.

countrystring · query string

ISO country code or europe.

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

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.

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

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.

Example -count·Where the value comes from Choose name, -name, count, or -count.

limitinteger · query string

Maximum number of values.

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)

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.

countrystring · query string

ISO country code or europe.

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

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.

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

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.

Example -count·Where the value comes from Choose name, -name, count, or -count.

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

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.

countrystring · query string

ISO country code or europe.

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

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.

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

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

GET

/api/fuels

List canonical fuel groups available in current inventory.

Requires the search scope.

Parameters

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.

countrystring · query string

ISO country code or europe.

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

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.

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

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

GET

/api/gearboxes

List canonical gearbox groups available in current inventory.

Requires the search scope.

Parameters

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.

countrystring · query string

ISO country code or europe.

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

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.

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

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

GET

/api/countries

List vehicle-location countries and display names.

Requires the search scope.

Parameters

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.

countrystring · query string

ISO country code or europe.

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

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.

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

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

GET

/api/sites

List auction source slugs with live inventory counts.

Requires the search scope.

Parameters

damagedboolean · query string

Restrict counts to damaged or broken vehicles.

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

buy_nowboolean · query string

Restrict counts to Buy-Now inventory.

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": "japanauction",
      "count": 1642
    }
  ]
}

GET

/load-models

Return the complete model catalog grouped by brand.

Requires the search scope.

Parameters

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.

countrystring · query string

ISO country code or europe.

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

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.

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

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