LogoLogo
API StatusSupportPostmanContact Us
🇳🇿 NZ AutoGrab API Doc
🇳🇿 NZ AutoGrab API Doc
  • AutoGrab Basics
    • AutoGrab Developer Hub
    • Integration Overview
    • Open API Reference
    • API & System Status
    • API Test Cases
  • Authentication
    • Basic Key Based Authentication
    • OAuth Authentication
  • Vehicle Search
    • Vehicle Searching Basics
    • Plain-text Search
    • Registration Plate Search
    • VIN Search
    • Facet Search
      • Facet Integration Worked Example
    • Marketplace ID Lookup
    • Vehicle ID Search
    • Matching Confidence
  • Sourcing
    • Sourcing Basics
    • Market Overlay
      • Features
    • Market Statistics
  • Vehicle Data
    • Vehicle Data Basics
    • Vehicle History
    • Factory Build Data
  • Valuation
    • Valuation Basics
    • Valuation Predictions
      • Adjustments
      • Condition Array
      • Valuation Features
    • Residual Valuations
    • Registration & VIN Valuations
    • Valuation Features
    • Max Offer Configuration
    • AutoGauge
  • Embeddable Products
    • Embeddable Basics
    • AutoGauge
    • Valuation Widget
    • Market Insights Snapshot
  • Other Products & Resources
    • Pre-Accident Valuation API Suite
    • URL Linking Structure
    • Webhooks Integration
    • Customer Recapture
    • Brand Guidelines
    • API Reference Parameter
    • Stock Feeds
    • FAQ
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
  2. Facet Search

Facet Integration Worked Example

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.

Form your request for a list of Models

/v2/vehicles/facets?region=nz&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 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.

Form your request for a list of badges

v2/vehicles/facets?model=Corolla&region=nz&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 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.

/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 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"
}
PreviousFacet SearchNextMarketplace ID Lookup

Was this helpful?