Facet Search

This API is ideally suited to assisting customers to find a vehicle via your website's or application's drop down boxes and is an alternative to using our plate or vin lookup service.

For example there may be instances where your customer doesn't know the plate of the vehicle they want some information from you on. Here you can use the Facet Search API to incrementally help the customer to find their vehicle.

First step is to start with a year drop down (you don't need MotorWeb for that), the customer selects the year of the vehicle (2022 in this example).

Second step, populate your "Make" dropdown box with the make values returned from our API by specifying the facet=year,make&year=2022 (customer selects "Mitsubishi" in this example).

Third step, populate your "Model" drop down box with the model values returned from our API by specifying the facet=year,make,model&year=2022&make=Mitsubishi (customer selects "Outlander" in this example).

At the time of writing, there were 30 variants of the 2022 Mitsubishi Outlander which is a bit much for a customer to wade through, so a "Badge" or "Variant" dropdown box would be a good idea.

Fourth step, populate your "Badge" drop down box with the badge values returned from our API by specifying the facet=year,make,model,badge&year=2022&make=Mitsubishi&model=Outlander (customer selects "PHEV XLS" in this example).

At the time of writing, there were 2 versions of the 2022 Mitsubishi Outlander PHEV XLS which now allows you to use our "Search Vehicle by Facets" API.

By providing the data above information 2022 Mitsubishi Outlander PHEV XLS as returned in the API to the "Search Vehicle by Facets" API you can show your customer the 2 vehicles to select from.

A good example of using Facets API is Westside Auto.

Westside Auto Facet Search

Get vehicle count by facet

get

Retrieve counts of available vehicles according to facet filters

Query parameters
facetstringRequired

The facet parameter filters results by specific attributes such as 'make' and returns their counts.

Example: year,make,model,badge
yearstringOptional

The build year of the vehicle

Example: 2009
makestringOptional

The make of the vehicle

Example: Nissan
modelstringOptional

The model of the vehicle

Example: Skyline
badgestringOptional

The badge of the vehicle

Example: 370GT Type SP
seriesstringOptional

The series of the vehicle

Example: V36
transmissionstringOptional

The specific transmission type (e.g. Sports Automatic, Automated Manual, etc...)

Example: Sports Automatic
body_typestringOptional

The body type of the vehicle (e.g. Hatchback, Sedan, etc...)

Example: Sedan
fuelstringOptional

The fuel type of the vehicle (e.g. Petrol, Diesel, etc...)

Example: Petrol
drivestringOptional

The specific drive type (e.g. AWD, 4WD, 4x4 Dual Range, etc...)

Example: RWD
limitintegerOptional

The maximum number of results to return per facet query (default: 5)

Example: 5
Responses
200

Vehicle Count By Facet Response

application/json
get
/v1/vehicles/facets
GET /v1/vehicles/facets?facet=year%2Cmake%2Cmodel%2Cbadge HTTP/1.1
Host: 
Accept: */*

{
  "success": "true",
  "facets": {
    "year": [
      {
        "year": 2007,
        "make": "Mitsubishi",
        "model": "Outlander",
        "count": 118
      }
    ],
    "make": [
      {
        "year": 2007,
        "make": "Mitsubishi",
        "model": "Outlander",
        "count": 118
      }
    ],
    "model": [
      {
        "year": 2007,
        "make": "Mitsubishi",
        "model": "Outlander",
        "count": 118
      }
    ],
    "badge": [
      {
        "year": 2007,
        "make": "Mitsubishi",
        "model": "Outlander",
        "count": 118
      }
    ],
    "series": [
      {
        "year": 2007,
        "make": "Mitsubishi",
        "model": "Outlander",
        "count": 118
      }
    ],
    "transmission": [
      {
        "year": 2007,
        "make": "Mitsubishi",
        "model": "Outlander",
        "count": 118
      }
    ],
    "body_type": [
      {
        "year": 2007,
        "make": "Mitsubishi",
        "model": "Outlander",
        "count": 118
      }
    ],
    "fuel": [
      {
        "year": 2007,
        "make": "Mitsubishi",
        "model": "Outlander",
        "count": 118
      }
    ],
    "drive": [
      {
        "year": 2007,
        "make": "Mitsubishi",
        "model": "Outlander",
        "count": 118
      }
    ]
  },
  "vehicles": [
    {
      "id": "2983792384791283",
      "title": "2020 Tesla Model S Performance Auto AWD",
      "score": 25.11
    }
  ]
}
PreviousSearch Vehicle by FacetsNextMarket Overlay

Last updated