LogoLogo
API StatusSupportPostmanContact Us
🇬🇧 UK AutoGrab API Doc
🇬🇧 UK AutoGrab API Doc
  • AutoGrab Basics
    • AutoGrab Developer Hub
    • Integration Overview
    • API Test Cases
    • FAQ
  • Authentication
    • API Key
    • OAuth Authentication
  • Vehicle Search
    • Vehicle Searching Basics
    • Plain-text Search
    • VRM Search
    • VIN Search
    • Facet Search
    • Vehicle ID Search
    • Marketplace ID Lookup
  • Sourcing
    • Sourcing Basics
    • Market Overlay
    • Market Statistics
    • Stock Feeds
  • Vehicle Data
    • Vehicle Data Basics
    • Recall Search
    • MOT & Tax Search
    • Vehicle History
    • Factory Build Data
    • Factory Fitted Options
  • Valuation
    • Valuation Basics
    • Valuation Predictions
    • Residual Valuations
    • Max Offer Configuration
    • Gauge API
  • Embeddable Products
    • Embeddable Basics
    • Gauge Widget
    • Valuation Widget
    • Market Overlay Widget
  • Customer Recapture
    • Customer Recapture
    • Webhooks Integration
  • Insurance
    • Pre-Accident Valuation
Powered by GitBook
LogoLogo

Links

  • Terms of Use

2024 © AutoGrab Pty Ltd. ABN 79 638 468 569

On this page

Was this helpful?

Export as PDF
  1. Vehicle Search

Facet Search

Use smart drop downs to find a vehicle.

PreviousVIN SearchNextVehicle ID Search

Last updated 5 months ago

Was this helpful?

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.

Facets User Interface Example

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

This function is useful when supplying data to drop-downs for display on a form. A good example of using the Facets API is .

Westside Auto

Retrieve counts of available vehicles according to facet filters

get

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

Authorizations
Query parameters
facetstringRequired
yearstringOptional
makestringOptional
modelstringOptional
badgestringOptional
seriesstringOptional
transmissionstringOptional
body_typestringOptional
fuelstringOptional
drivestringOptional
limitnumber · max: 100Optional

The maximum number of results to return per facet query

regionstring · enumOptional

The region to perform this request in

Possible values:
reference_idstringOptional

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

Responses
200
Success
application/json
400
Bad Request
application/json
401
Unauthorized
application/json
get
GET /v2/vehicles/facets/ HTTP/1.1
Host: api.autograb.com.au
ApiKey: YOUR_API_KEY
Accept: */*
{
  "success": true,
  "facets": {
    "year": [
      {
        "year": 1,
        "make": "text",
        "model": "text",
        "count": 1
      }
    ],
    "make": [
      {
        "year": 1,
        "make": "text",
        "model": "text",
        "count": 1
      }
    ],
    "model": [
      {
        "year": 1,
        "make": "text",
        "model": "text",
        "count": 1
      }
    ],
    "badge": [
      {
        "year": 1,
        "make": "text",
        "model": "text",
        "count": 1
      }
    ],
    "series": [
      {
        "year": 1,
        "make": "text",
        "model": "text",
        "count": 1
      }
    ],
    "transmission": [
      {
        "year": 1,
        "make": "text",
        "model": "text",
        "count": 1
      }
    ],
    "body_type": [
      {
        "year": 1,
        "make": "text",
        "model": "text",
        "count": 1
      }
    ],
    "fuel": [
      {
        "year": 1,
        "make": "text",
        "model": "text",
        "count": 1
      }
    ],
    "drive": [
      {
        "year": 1,
        "make": "text",
        "model": "text",
        "count": 1
      }
    ]
  },
  "vehicles": [
    {
      "id": "text",
      "title": "text",
      "score": 1
    }
  ]
}

Search for a vehicle by facet, return matching vehicles

get

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

Authorizations
Query parameters
yearstringOptional

The build year of the vehicle

makestringOptional

The make of the vehicle

modelstringOptional

The model of the vehicle

badgestringOptional

The badge of the vehicle

seriesstringOptional

The series of the vehicle

transmissionstringOptional

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

transmission_typestringOptional

The basic transmission type (i.e. Automatic, Manual or Reduction Gear)

body_typestringOptional

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

fuelstringOptional

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

drivestringOptional

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

drive_typestringOptional

The basic drive type of the vehicle (e.g. Front Wheel Drive, Rear Wheel Drive, etc...)

limitnumber · max: 100Optional

The maximum number of results to return per facet query

regionstring · enumOptional

The region to perform this request in

Possible values:
reference_idstringOptional

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

Responses
200
Success
application/json
400
Bad Request
application/json
401
Unauthorized
application/json
get
GET /v2/vehicles/facets/search HTTP/1.1
Host: api.autograb.com.au
ApiKey: YOUR_API_KEY
Accept: */*
{
  "success": true,
  "vehicles": [
    {
      "id": "text",
      "title": "text",
      "year": 1,
      "make": "text",
      "model": "text",
      "badge": "text",
      "series": "text",
      "model_year": "text",
      "release_month": 1,
      "release_year": 1,
      "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": 1,
      "num_seats": 1,
      "num_gears": 1,
      "num_cylinders": 1,
      "capacity_cc": 1,
      "power_kw": 1,
      "torque_nm": 1,
      "range": 1
    }
  ],
  "total": 1
}
  • Search for Vehicles by facets
  • GETRetrieve counts of available vehicles according to facet filters
  • GETSearch for a vehicle by facet, return matching vehicles
  • Facets User Interface Example
  • Facet Integration Worked Example
  • Form your GET request for Makes
  • Form your request for a list of Models.
  • Form your request for a list of Badges