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.

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: make

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

reference_idstringOptional

An optional reference id which will be stored against usage records if supplied

Example: MY_REFERENCE_123

Responses

200

Vehicle Count By Facet Response

application/json

successbooleanOptionalExample: true

400

Bad Request / Validation Failed

application/json

404

Resource for id cannot be found

application/json

500

Unknown error on the service side

application/json

get

/v1/vehicles/facets

HTTPcURLJavaScriptPython

GET /v1/vehicles/facets?facet=make HTTP/1.1
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
    }
  ]
}