Facet Search

Use smart drop downs to find a vehicle.

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.

Retrieve counts of available vehicles according to facet filters

Allows caller to retrieve specific counts of available vehicles according to specific facet filters

GET/v2/vehicles/facets/

Authorization

Query parameters

Response

Success

Body

successboolean

facetsobject

vehiclesarray of object

Request

const response = await fetch('/v2/vehicles/facets/?facet=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "success": true,
  "facets": {
    "year": [
      {
        "year": 0,
        "make": "text",
        "model": "text",
        "count": 0
      }
    ],
    "make": [
      {
        "year": 0,
        "make": "text",
        "model": "text",
        "count": 0
      }
    ],
    "model": [
      {
        "year": 0,
        "make": "text",
        "model": "text",
        "count": 0
      }
    ],
    "badge": [
      {
        "year": 0,
        "make": "text",
        "model": "text",
        "count": 0
      }
    ],
    "series": [
      {
        "year": 0,
        "make": "text",
        "model": "text",
        "count": 0
      }
    ],
    "transmission": [
      {
        "year": 0,
        "make": "text",
        "model": "text",
        "count": 0
      }
    ],
    "body_type": [
      {
        "year": 0,
        "make": "text",
        "model": "text",
        "count": 0
      }
    ],
    "fuel": [
      {
        "year": 0,
        "make": "text",
        "model": "text",
        "count": 0
      }
    ],
    "drive": [
      {
        "year": 0,
        "make": "text",
        "model": "text",
        "count": 0
      }
    ]
  },
  "vehicles": [
    {
      "id": "text",
      "title": "text",
      "score": 0
    }
  ]
}

Search for a vehicle by facet, return matching vehicles

Search for vehicles by facets - minimum of year, make and model are required to return results and additional facets

GET/v2/vehicles/facets/search

Authorization

Query parameters

Response

Success

Body

successboolean

vehiclesarray of object

totalnumber

Request

const response = await fetch('/v2/vehicles/facets/search', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "success": true,
  "vehicles": [
    {
      "id": "text",
      "title": "text",
      "year": 0,
      "make": "text",
      "model": "text",
      "badge": "text",
      "series": "text",
      "model_year": "text",
      "release_month": 0,
      "release_year": 0,
      "body_type": "text",
      "body_config": "text",
      "transmission": "text",
      "transmission_type": "text",
      "wheelbase": "text",
      "wheelbase_type": "text",
      "fuel": "text",
      "fuel_type": "text",
      "engine": "text",
      "engine_type": "text",
      "drive": "text",
      "drive_type": "text",
      "num_doors": 0,
      "num_seats": 0,
      "num_gears": 0,
      "num_cylinders": 0,
      "capacity_cc": 0,
      "power_kw": 0,
      "torque_nm": 0,
      "range": 0
    }
  ],
  "total": 0
}

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.

For a preview of how facets in implemented inside the AutoGrab web app see the video below.

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

{
    "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

{
    "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&region=au&make=Toyota&facet=badge

{
    "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.

/v2/vehicles/facets/search?region=nz&badge=Sprint&make=Toyota&model=Corolla

{
    "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 too many vehicles to search for. 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"
}

PreviousVIN Search NextVehicle ID Search

Last updated 1 month ago