facets

Full brand to models map

The whole brand-to-models map in one call, for building a cascading filter UI without a round trip per brand. Heavy — cache it. country is accepted and ignored here.

This response is shaped differently from every other facet route. The body is the brand map: every key is a brand name and every value is that brand's model list. There is no wrapper object, no success field and no contract metadata on a successful response — the keys are data, so nothing else may share that namespace. The correlation id is on the X-Request-ID response header instead.

An error response is wrapped, and does carry success: false.

get/load-models

Request

  • Base URL: https://api.thecarapi.com
  • URL: https://api.thecarapi.com/load-models
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer
    • API key in query parameter api_key

Query parameters

damagedboolean

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

buy_nowboolean

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

countrystring
Example:DE

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

brandstring
Example:bmw

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

modelstring
Example:320d

Model name or slug.

year_frominteger
Example:2018

Lower bound on registration year, inclusive.

year_tointeger
Example:2024

Upper bound on registration year, inclusive.

production_year_frominteger
Example:2018

Lower bound on production year, inclusive. production_year falls back to the registration year where the source publishes no build year, with registration-year fallback when build-year evidence is absent.

production_year_tointeger
Example:2024

Upper bound on production year, inclusive.

fuelstring
Example:Diesel

Canonical fuel group from /api/fuels.

gearboxstring
Example:Automatic

Canonical gearbox group from /api/gearboxes.

kilometers_frominteger

Lower bound on mileage in kilometres.

kilometers_tointeger

Upper bound on mileage in kilometres.

horsepower_frominteger
horsepower_tointeger
price_frominteger

Lower bound on the public EUR price.

price_tointeger

Upper bound on the public EUR price.

typestring
Example:520d

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

vehicle_type'cars' | 'suvs & trucks' | 'suvs and trucks'
body_stylestring
ending_soonboolean

true restricts to auctions ending within roughly two hours.

sitestring
Example:openlane,ecarstrade

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.

site_excludestring
Example:copart

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

steering'left' | 'lhd' | 'left-hand' | 'left_hand' | 'right' | 'rhd' | 'right-hand' | 'right_hand'
Example:left

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.

Headers

If-None-Matchstring
Example:W/"6f1c0a9d8e"

Echo back the ETag from your last response for this URL. An unchanged page answers 304 Not Modified with no body. ETags are weak, so the tag stays valid whether or not the body came back compressed.

Response

The brand map itself. Every key is a brand; iterate them directly.

object required

Brand name to its available models.

Example response

{
  "Audi": [
    {
      "text": "A4"
    }
  ],
  "BMW": [
    {
      "text": "320d"
    },
    {
      "text": "X5"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.