> 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/nz-autograb-api-doc/vehicle-search/facet-search/facet-integration-worked-example.md). # Facet Integration Worked Example Read a step by step example guide on how to work with Facets. 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=nz&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 NZ 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=nz&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 NZ 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=nz&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 NZ 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. `/v2/vehicles/facets/search?region=nz&badge=Sprint&make=Toyota&model=Corolla` ```json { "success": true, "vehicles": [ { "id": "5364630897557504", "region": "nz", "title": "1997 Toyota Corolla Sprint Manual", "year": "1997", "make": "Toyota", "model": "Corolla", "badge": "Sprint", "series": null, "model_year": null, "release_month": 9, "release_year": 1995, "body_type": "Hatchback", "body_config": null, "transmission": "Manual", "transmission_type": "Manual", "wheelbase": null, "wheelbase_type": null, "fuel": "Petrol", "fuel_type": "Petrol", "engine": "Piston", "engine_type": "Piston", "drive": "FWD", "drive_type": "Front Wheel Drive", "num_doors": 5, "num_seats": 5, "num_gears": 5, "num_cylinders": 4, "capacity_cc": 1587, "power_kw": null, "torque_nm": null, "range": null, "options": [] }, { "id": "6033133967245312", "region": "nz", "title": "1999 Toyota Corolla Sprint Manual", "year": "1999", "make": "Toyota", "model": "Corolla", "badge": "Sprint", "series": null, "model_year": null, "release_month": 9, "release_year": 1995, "body_type": "Hatchback", "body_config": null, "transmission": "Manual", "transmission_type": "Manual", "wheelbase": null, "wheelbase_type": null, "fuel": "Petrol", "fuel_type": "Petrol", "engine": "Piston", "engine_type": "Piston", "drive": "FWD", "drive_type": "Front Wheel Drive", "num_doors": 5, "num_seats": 5, "num_gears": 5, "num_cylinders": 4, "capacity_cc": 1587, "power_kw": null, "torque_nm": null, "range": null, "options": [] }, { "id": "6563011892346880", "region": "nz", "title": "1998 Toyota Corolla Sprint Manual", "year": "1998", "make": "Toyota", "model": "Corolla", "badge": "Sprint", "series": null, "model_year": null, "release_month": 9, "release_year": 1995, "body_type": "Hatchback", "body_config": null, "transmission": "Manual", "transmission_type": "Manual", "wheelbase": null, "wheelbase_type": null, "fuel": "Petrol", "fuel_type": "Petrol", "engine": "Piston", "engine_type": "Piston", "drive": "FWD", "drive_type": "Front Wheel Drive", "num_doors": 5, "num_seats": 5, "num_gears": 5, "num_cylinders": 4, "capacity_cc": 1587, "power_kw": null, "torque_nm": null, "range": null, "options": [] } ], "total": 3 } ``` If you do not pay attention to the counts under each facet there may be to many vehicle to perform a search on. 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 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/nz-autograb-api-doc/vehicle-search/facet-search/facet-integration-worked-example.md?ask=&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.