> For the complete documentation index, see [llms.txt](https://devhub.autograb.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devhub.autograb.com/eu-autograb-api-doc/vehicle-search/facet-search.md).

# Facet Search

Use smart drop downs to find a vehicle.

The Vehicle Facets API narrows a vehicle down by its attributes, one selection at a time. Every attribute returned on a vehicle record can now be used two ways: as a `facet` to get the list of available values and counts, and as an optional filter to narrow the results.

That means you can drive a drop-down off `model_year`, filter by `num_doors=5`, or restrict to `fuel_type=Electric`, using the same request pattern as `make`, `model` and `badge`. All filters are optional, and every field works in every region where that data is populated: `au`, `nz`, `uk`, `my` and `eu`.

### Supported facets <a href="#supported-facets" id="supported-facets"></a>

36 fields are supported. Example values come from a 2020 Mercedes-Benz A45 AMG S (W177).

#### Identity <a href="#identity" id="identity"></a>

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Example</td></tr><tr><td><code>year</code></td><td>string</td><td><code>2020</code></td></tr><tr><td><code>make</code></td><td>string</td><td><code>Mercedes-Benz</code></td></tr><tr><td><code>model</code></td><td>string</td><td><code>A-Class</code></td></tr><tr><td><code>badge</code></td><td>string</td><td><code>A45 AMG S</code></td></tr><tr><td><code>series</code></td><td>string</td><td><code>W177</code></td></tr><tr><td><code>model_year</code></td><td>string</td><td><code>MY20</code></td></tr><tr><td><code>release_month</code></td><td>number</td><td><code>2</code></td></tr><tr><td><code>release_year</code></td><td>number</td><td><code>2020</code></td></tr><tr><td><code>import_status</code></td><td>string</td><td><code>Sold Locally</code></td></tr></tbody></table>

#### Body <a href="#body" id="body"></a>

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Example</td></tr><tr><td><code>body_type</code></td><td>string</td><td><code>Hatchback</code></td></tr><tr><td><code>body_config</code></td><td>string</td><td>Body configuration, where recorded (commercial vehicles)</td></tr><tr><td><code>roof_type</code></td><td>string</td><td>Roof style, where recorded</td></tr><tr><td><code>num_doors</code></td><td>number</td><td><code>5</code></td></tr><tr><td><code>num_seats</code></td><td>number</td><td><code>5</code></td></tr><tr><td><code>num_berths</code></td><td>number</td><td>Sleeping berths, where recorded (motorhomes, campervans)</td></tr></tbody></table>

#### Drivetrain and engine <a href="#drivetrain-and-engine" id="drivetrain-and-engine"></a>

| Parameter           | Type   | Example                                            |
| ------------------- | ------ | -------------------------------------------------- |
| `transmission`      | string | `Dual Clutch Automatic (DCT)`                      |
| `transmission_type` | string | `Automatic`                                        |
| `num_gears`         | number | `8`                                                |
| `drive`             | string | `AWD`                                              |
| `drive_type`        | string | `Four Wheel Drive`                                 |
| `fuel`              | string | `Petrol`                                           |
| `fuel_type`         | string | `Petrol`                                           |
| `engine`            | string | `Piston`                                           |
| `engine_type`       | string | `Piston`                                           |
| `num_cylinders`     | number | `4`                                                |
| `capacity_cc`       | number | `1991`                                             |
| `power_kw`          | number | `310`                                              |
| `torque_nm`         | number | `500`                                              |
| `range`             | number | `699`                                              |
| `battery_kwh`       | number | Battery capacity, where recorded (EVs and hybrids) |

#### Dimensions and mass <a href="#dimensions-and-mass" id="dimensions-and-mass"></a>

| Parameter           | Type   | Example                                                    |
| ------------------- | ------ | ---------------------------------------------------------- |
| `wheelbase`         | string | Wheelbase description, where recorded                      |
| `wheelbase_type`    | string | Wheelbase category, where recorded                         |
| `num_axles`         | number | Axle count, where recorded (heavy and commercial vehicles) |
| `weight_kg`         | number | Vehicle weight, where recorded                             |
| `length_mm`         | number | Overall length, where recorded                             |
| `max_laden_mass_kg` | number | Maximum laden mass, where recorded                         |

{% hint style="info" %}
**Note:** not every parameter is recorded for every vehicle category. For example, we don't record `num_berths` for cars, so a car search filtered on it returns no results.
{% endhint %}

The paired fields (`transmission` and `transmission_type`, `drive` and `drive_type`, `fuel` and `fuel_type`, `engine` and `engine_type`) give you a detailed value and a grouped value. Use the grouped value for a broad first drop-down, for example Automatic vs Manual, then the detailed value to refine.

### How facets and filters work <a href="#how-facets-and-filters-work" id="how-facets-and-filters-work"></a>

Any field in the tables above can be passed in two places on the same request.

* **As the facet.** `facet=model_year` returns every available `model_year` value with a vehicle count. Request several at once with a comma-separated list: `facet=badge,series,transmission`.
* **As a filter.** `model_year=MY20` limits results to vehicles with that value. Combine as many filters as you like; they are joined with AND.

Rules that apply to every field:

* All filters are optional. Omit any field you don't need.
* Pass string values exactly as the facets endpoint returns them, URL-encoded (`transmission=Dual%20Clutch%20Automatic%20(DCT)`).
* Pass numeric values as whole numbers with no units (`power_kw=310`, not `310kW`).
* `limit` caps the values returned per facet, up to 100.
* Every field may not be available in every region. Where a region doesn't record a field (for example `num_berths` on passenger vehicles), the facet returns an empty list and the filter matches no vehicles.

### Endpoints <a href="#endpoints" id="endpoints"></a>

Both endpoints accept the same 36 filter parameters.

| Endpoint                         | Returns                                      | Parameters                                             |
| -------------------------------- | -------------------------------------------- | ------------------------------------------------------ |
| `GET /v2/vehicles/facets`        | Values and counts for the requested facet(s) | `facet`, `region`, any filter, `limit`, `reference_id` |
| `GET /v2/vehicles/facets/search` | Matching vehicle records                     | `region`, any filter, `reference_id`                   |

| Parameter           | Type             | Notes                                                                    |
| ------------------- | ---------------- | ------------------------------------------------------------------------ |
| `facet`             | string           | Field(s) to aggregate. Any supported field, comma-separated for several. |
| `region`            | string, enum     | `au`, `nz`, `uk`, `my`                                                   |
| Any supported field | string or number | Optional filter. See Supported facets.                                   |
| `limit`             | number, max 100  | Maximum values returned per facet.                                       |
| `reference_id`      | string           | Optional. Stored against usage records if supplied.                      |

### Facets user interface example <a href="#facets-user-interface-example" id="facets-user-interface-example"></a>

Facets feed form drop-downs: each selection filters the next list. [Westside Auto](https://www.westsideauto.com.au/) uses the Facets API this way on its vehicle search.

The new fields let you go past Make, Model, Badge. A buyer looking for a seven-seat diesel can start with `num_seats` and `fuel_type`, then pick from the makes that actually match.

For a preview of facets inside the AutoGrab web app, see the [video walkthrough](https://www.loom.com/share/a19c3e50f95f4ed286583956c2e22693).

### Worked example <a href="#worked-example" id="worked-example"></a>

The goal: get your user to a short list of vehicles, one drop-down at a time. Each step adds the previous selection as a filter and asks for the next facet. Counts in the responses below are trimmed and illustrative.

#### 1. Get makes <a href="#id-1-get-makes" id="id-1-get-makes"></a>

```
GET /v2/vehicles/facets?region=au&facet=make
```

```json
{
  "success": true,
  "make": [
    { "value": "Abarth", "count": 47 },
    { "value": "Alfa Romeo", "count": 713 },
    { "value": "Mercedes-Benz", "count": 4212 }
  ]
}
```

Your user picks *Mercedes-Benz*.

#### 2. Get model years (new) <a href="#id-2-get-model-years-new" id="id-2-get-model-years-new"></a>

Narrow by model year before model. This is useful when the user knows their car's compliance or model year but not the exact model name.

```
GET /v2/vehicles/facets?region=au&make=Mercedes-Benz&facet=model_year
```

```json
{
  "success": true,
  "model_year": [
    { "value": "MY19", "count": 188 },
    { "value": "MY20", "count": 203 },
    { "value": "MY21", "count": 176 }
  ]
}
```

Your user picks *MY20*.

#### 3. Get models <a href="#id-3-get-models" id="id-3-get-models"></a>

```
curl --location 'https://api.autograb.com.au/v2/vehicles/facets?facet=model&region=au&make=Mercedes-Benz&model_year=MY20' \
--header 'ApiKey: YOURKEY'
```

```json
{
  "success": true,
  "model": [
    { "value": "A-Class", "count": 14 },
    { "value": "C-Class", "count": 21 },
    { "value": "GLC", "count": 17 }
  ]
}
```

Your user picks *A-Class*.

#### 4. Refine with several facets at once (new) <a href="#id-4-refine-with-several-facets-at-once-new" id="id-4-refine-with-several-facets-at-once-new"></a>

Ask for more than one facet in a single call to fill several drop-downs together.

```
GET /v2/vehicles/facets?region=au&make=Mercedes-Benz&model_year=MY20&model=A-Class&facet=badge,body_type,transmission_type
```

```json
{
  "success": true,
  "badge": [
    { "value": "A180", "count": 2 },
    { "value": "A250", "count": 4 },
    { "value": "A45 AMG S", "count": 2 }
  ],
  "body_type": [
    { "value": "Hatchback", "count": 9 },
    { "value": "Sedan", "count": 5 }
  ],
  "transmission_type": [
    { "value": "Automatic", "count": 14 }
  ]
}
```

Your user picks *A45 AMG S* and *Hatchback*.

#### 5. Load the vehicles <a href="#id-5-load-the-vehicles" id="id-5-load-the-vehicles"></a>

Once the counts are small, pass the same filters to `/facets/search` to get the full records.

```
curl --location 'https://api.autograb.com.au/v2/vehicles/facets/search?region=au&make=Mercedes-Benz&model_year=MY20&model=A-Class&badge=A45%20AMG%20S&body_type=Hatchback' \
--header 'ApiKey: YOURKEY'
```

```json
{
  "success": true,
  "vehicles": [
    {
      "region": "au",
      "title": "2020 Mercedes-Benz A-Class A45 AMG S Auto 4MATIC",
      "year": "2020",
      "make": "Mercedes-Benz",
      "model": "A-Class",
      "badge": "A45 AMG S",
      "series": "W177",
      "model_year": "MY20",
      "release_month": 2,
      "release_year": 2020,
      "body_type": "Hatchback",
      "transmission": "Dual Clutch Automatic (DCT)",
      "transmission_type": "Automatic",
      "fuel": "Petrol",
      "drive": "AWD",
      "drive_type": "Four Wheel Drive",
      "num_doors": 5,
      "num_seats": 5,
      "num_gears": 8,
      "num_cylinders": 4,
      "capacity_cc": 1991,
      "power_kw": 310,
      "torque_nm": 500,
      "import_status": "Sold Locally"
    }
  ],
  "is_paginated": false,
  "count": 1
}
```

The record above is trimmed. Search responses return every field listed in Supported facets.

#### Filtering on numbers <a href="#filtering-on-numbers" id="filtering-on-numbers"></a>

Numeric fields work the same way. This returns every five-door, five-seat AWD petrol hatch in AU with 310 kW:

```
GET /v2/vehicles/facets?region=au&facet=model&body_type=Hatchback&num_doors=5&num_seats=5&drive=AWD&fuel_type=Petrol&power_kw=310
```

### Errors and limits <a href="#errors-and-limits" id="errors-and-limits"></a>

Watch the counts before you call `/facets/search`. If too many vehicles match, the search is rejected:

```json
{
  "error": true,
  "message": "Too many vehicles, you must return at least make, model, badge, series, year"
}
```

The new filters narrow results, but they don't replace this requirement. Filtering on `model_year` or `power_kw` alone still returns this error; add the identity filters, or keep refining with facets until the count is small.

Each facet returns at most 100 values. Set `limit` for a lower cap.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://devhub.autograb.com/eu-autograb-api-doc/vehicle-search/facet-search.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.