# Facet Search
### Search for Vehicles by facets
The Vehicle Facets API allows you to narrow down the matching vehicle based on the vehicle's parameters. The facets available are: `year`, `make`, `model`, `badge`, `series`, `transmission`, `body`, `body_style`, `fuel`, `engine` and `wheelbase`.
If you would like to return aggregations of factes, use a comma-separated list in the `facets` field: eg. `facets=badge,series,transmission`.
{% openapi src="" path="/v2/vehicles/facets/" method="get" %}
[insurance\_updated.yaml](https://4010475651-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFaCA1JqFKRrqIB0EfZlZ%2Fuploads%2FuDtxATuz0g12x4lhufjn%2Finsurance_updated.yaml?alt=media\&token=2565c3ea-325e-4bf3-b8e4-31792a5c9e79)
{% endopenapi %}
{% openapi src="" path="/v2/vehicles/facets/search" method="get" %}
[insurance\_updated.yaml](https://4010475651-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFaCA1JqFKRrqIB0EfZlZ%2Fuploads%2FuDtxATuz0g12x4lhufjn%2Finsurance_updated.yaml?alt=media\&token=2565c3ea-325e-4bf3-b8e4-31792a5c9e79)
{% endopenapi %}
## Facets User Interface Example
This function is useful when supplying data to drop-downs for display on a form. A good example of using Facets API is [Westside Auto](https://www.westsideauto.com.au/).
For a preview of how facets in implemented inside the AutoGrab web app see the video below.
{% embed url="" %}
## Facet Integration Worked Example
Let's work backwards from the end result which is one or a few results for your user to pick from driven by previous drop-down. There are a few ways to make facets work for you, we'll go through the most common integration method.
### **Form your GET request for Makes**
```
/v2/vehicles/facets?region=au&facet=make
```
```json
{
"success": true,
"make": [
{
"value": "Abarth",
"count": 47
},
{
"value": "Acura",
"count": 1
},
{
"value": "Alfa Romeo",
"count": 713
},
{
"value": "AM General",
"count": 2
},
{
"value": "Aston Martin",
"count": 169
// trimmed - this would show all makes in the AU region
```
Ask your user to choose a make from the list then call all available models based on that selection. Let's say your user chose *Toyota*.
### **Form your request for a list of Models**
```
/v2/vehicles/facets?region=au&make=Toyota&facet=model
```
```json
{
"success": true,
"model": [
{
"value": "4Runner",
"count": 41
},
{
"value": "86",
"count": 72
},
{
"value": "Allex",
"count": 26
// trimmed - this would show all models in the AU region
```
Ask your user to choose a Model from the list then call all available models based on that selection. Let's say your user chose *Corolla*.
### **Form your request for a list of Badges**
```
v2/vehicles/facets?model=Corolla®ion=au&make=Toyota&facet=badge
```
```json
{
"success": true,
"badge": [
{
"value": "SE Ltd",
"count": 6
},
{
"value": "SE LTD",
"count": 2
},
{
"value": "Sprint",
"count": 3
},
{
"value": "Sprinter",
"count": 5
},
{
"value": "Sprinter SR",
"count": 1
},
{
"value": "SR",
"count": 4
},
// trimmed - this would show all badges in the AU region
```
**Select A Badge A Load Vehicles From A Search**
Ask your user to choose a badge from the list. Let's say your user chose Sprint. You can see the count is 3, meaning there are only 2 badges. You could send that directly to them or repeat the process with the year (`&facet=year`) to refine it further.
Let's say you'd like to present the three options to the user.
{% code overflow="wrap" %}
```json
curl --location 'https://api.autograb.com.au/v2/vehicles/facets/search?region=au&make=Toyota&model=Corolla&badge=Sprinter' \
--header 'ApiKey: YOURKEY'
```
{% endcode %}
```json
{
"success": true,
"vehicles": [
{
"id": "4765277606641664",
"region": "au",
"title": "1969 Toyota Corolla Sprinter Manual",
"year": "1969",
"make": "Toyota",
"model": "Corolla",
"badge": "Sprinter",
"series": "KE15",
"model_year": "MY69",
"release_month": 1,
"release_year": 1969,
"body_type": "Coupe",
"body_config": null,
"transmission": "Manual",
"transmission_type": "Manual",
"wheelbase": null,
"wheelbase_type": null,
"fuel": "Petrol",
"fuel_type": "Petrol",
"engine": "Piston",
"engine_type": "Piston",
"drive": "RWD",
"drive_type": "Rear Wheel Drive",
"num_doors": 2,
"num_seats": 4,
"num_gears": 4,
"num_cylinders": 4,
"capacity_cc": null,
"power_kw": null,
"torque_nm": null,
"range": null,
"battery_kwh": null,
"roof_type": null,
"options": []
},
{
"id": "5353417878798336",
"region": "au",
"title": "1970 Toyota Corolla Sprinter Manual",
"year": "1970",
"make": "Toyota",
"model": "Corolla",
"badge": "Sprinter",
"series": "KE17",
"model_year": "MY70",
"release_month": 1,
"release_year": 1970,
"body_type": "Coupe",
"body_config": null,
"transmission": "Manual",
"transmission_type": "Manual",
"wheelbase": null,
"wheelbase_type": null,
"fuel": "Petrol",
"fuel_type": "Petrol",
"engine": "Piston",
"engine_type": "Piston",
"drive": "RWD",
"drive_type": "Rear Wheel Drive",
"num_doors": 2,
"num_seats": 4,
"num_gears": 4,
"num_cylinders": 4,
"capacity_cc": null,
"power_kw": null,
"torque_nm": null,
"range": null,
"battery_kwh": null,
"roof_type": null,
"options": []
},
{
"id": "6735602443616256",
"region": "au",
"title": "1968 Toyota Corolla Sprinter Manual",
"year": "1968",
"make": "Toyota",
"model": "Corolla",
"badge": "Sprinter",
"series": "KE15",
"model_year": "MY68",
"release_month": 6,
"release_year": 1968,
"body_type": "Coupe",
"body_config": null,
"transmission": "Manual",
"transmission_type": "Manual",
"wheelbase": null,
"wheelbase_type": null,
"fuel": "Petrol",
"fuel_type": "Petrol",
"engine": "Piston",
"engine_type": "Piston",
"drive": "RWD",
"drive_type": "Rear Wheel Drive",
"num_doors": 2,
"num_seats": 4,
"num_gears": 4,
"num_cylinders": 4,
"capacity_cc": null,
"power_kw": null,
"torque_nm": null,
"range": null,
"battery_kwh": null,
"roof_type": null,
"options": []
}
],
"is_paginated": false,
"count": 3
}
```
If you do not pay attention to the counts under each facet, there may be too many vehicles to search for. You will know you have triggered this limitation if you see the error below.
```json
{
"error": true,
"message": "Too many vehicles, you must return at least make, model, badge, series, year"
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://devhub.autograb.com/vehicle-search/facet-search.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.
