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
{"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.
{"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.
{"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.
{"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.
{"error":true,"message":"Too many vehicles, you must return at least make, model, badge, series, year"}
