Vehicle Search API

The Vehicle Search API allows you to find matching vehicles within our database.

This API requires authentication and appropriate license attached to it.

Concepts

Concept	Definition
Vehicle	An object containing the title and metadata of a given vehicle.
Plain-text Search	Using plain text input to find a vehicle.
Aggregate Search	Sifting based on certain fields to narrow down matching vehicles.
Registration Search	Finding a matching vehicle based on its state registration.
VIN Search	Finding a matching vehicle based on its VIN.

Vehicle

Search for Vehicles by text

The Vehicle Search API allows you to search for matching vehicles by plain-text input. The API will return an array of vehicles & the confidence score in a match for that given vehicle.

The request requires a region, search string & API key. The default page length is 10, however you can adjust this based on your requirements.

Example

curl "https://api.autograb.com.au/v2/vehicles?search=2021%20Porsche%20911%20Carrera%20S%20Auto&region=au&count=10" \
     -H 'ApiKey: {API_KEY}'

You can explore this request further in the API Playground.

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.

This is useful when supplying data to dropdowns for display on a form. A good example using AutoGrab's Facets API is Westside Auto.

Registration Search

The Vehicle Registration API allows you to search for a vehicle by supplying its number plate. The request requires a region, the state (dependent on region), number plate & API key. This will return either a matching vehicle with possible option packs, or a null.

In all cases, and importantly if a matching vehicle is unable to be identified, we will return the upstream_vehicle field allowing you to identify how the relevant road transport authority describes the vehicle. Depending on your use case you may wish to allow front-end users to manually classify the vehicle using the upstream_vehicle as a guide to fill out a Facet style search (Vehicle Facets API) mentioned previously in this guide.

Australia

This feature is fully supported in Australia, state is required and you can find a reference table below. You must send the state in its short format, you can use the long format for front end purposes if you require.

State (Short)	State (Long)
NSW	New South Wales
NT	Northern Territory
QLD	Queensland
SA	South Australia
TAS	Tasmania
VIC	Victoria
WA	Western Australia
ACT	Australian Capital Territory

Example

curl "https://api.autograb.com.au/v2/vehicles/registrations/{number_plate}?region=au&state={state}" \
     -H 'ApiKey: {API_KEY}'

You can explore this request further in the API Playground.

New Zealand

This feature is fully supported in New Zealand. The state is not required for this region.

Malaysia

This feature is fully supported in Malaysia. The state is not required for this region.

Registration Status

To retrieve the registration status & write-off information for a given vehicle, you can call the status endpoint.

Australia

In Australia, merely call the /v2/vehicles/{number_plate}/status endpoint with region=au. You must send the state in its short format, you can use the long format for front end purposes if you require. Refer to the Australian state table under the Registration Search heading in this guide for a list.

Example

To perform an example request:

curl "https://api.autograb.com.au/v2/vehicles/registrations/{number_plate}/status?region=au&state={state}" \
     -H 'ApiKey: {API_KEY}'

An example response payload is:

{
  "success": true,
  "plate_number": "XYZ123",
  "state": "VIC",
  "vin": "YV1TS91Z041342423",
  "registration_status": "REGISTERED",
  "registration_expiry": "2022-09-12",
  "incidents": [
    {
      "type_code": "Storm, Flood, Other Write-off",
      "state": "VIC",
      "recorded_date": "2018-01-10",
      "code": "Repairable Write-off",
      "damage_codes": "H14B"
    }
  ]
}

New Zealand

This feature is not yet available in New Zealand.

Malaysia

This feature is not yet available in Malaysia.

Global Registration Plate Test Cases

You can utilise our test cases to confirm your implementation irrespective of region.

• REG4SUCCESS: Returns a successful lookup response with a high-quality vehicle match
• REG4WARNING: Returns a successful lookup response with a low-match quality warning
• REG4NOMATCH: Returns the VIN and vehicle description but no matching vehicle
• REG4VINONLY: Only returns the VIN and no other vehicle details

VIN Search

The Vehicle VIN API allows you to search for vehicle by the VIN.

The request requires only a region, vin & API key. This will return either a matching vehicle with possible option packs, or a null.

Example

curl "https://api.autograb.com.au/v2/vehicles/vins/{vin}?region=au" \
     -H 'ApiKey: {API_KEY}'

You can explore this request further in the API Playground.

Australia

This feature is fully supported in Australia.

New Zealand

This feature is fully supported in New Zealand.

Malaysia

This feature is not yet available in Malaysia.

Specs search

The Vehicle Specs API allows you to retrieve comprehensive vehicle specifications for any vehicle referenced by its Autograb Vehicle ID.

To retrieve a vehicle's specifications, you will need a region and a vehicle id.

Example

curl "https://api.autograb.com.au/v2/vehicles/{vehicle_id}/specs?region=au" \
     -H 'ApiKey: {API_KEY}'

Refer to the API docs for more information about the specs return payload.

Australia

This feature is fully supported in Australia.

New Zealand

This feature is fully supported in New Zealand.

Malaysia

This feature is not yet available in Malaysia.

Partial specs search

The Vehicle Partial Specs API allows you to retrieve partial specs relating to a vehicle. This is useful in situations where you are interested in specific details, and do not need to retrieve the whole specification listing.

Partial specs can be retrieved for any combination of the following specs categories: * base * safety * engine * power * ev_battery * drive * fuel * range * emissions * wheels * dimensions * weights * warranty * services * p_plate_status * options options

To retrieve a vehicle's partial specifications, you will need a region, a vehicle id and the list of partial specs categories.

Example to retrieve base, safety, fuel and range partial specs

curl "https://api.autograb.com.au/v2/vehicles/{vehicle_id}/specs?region=au&selectors=base,safety,fuel,range" \
     -H 'ApiKey: {API_KEY}'

Refer to the API docs for more information about the specs return payload.

Regional Coverage

This API relies upon the upstream Spec Search API, for its availability refer to the Spec Search summary in the section above.