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®ion=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 matchREG4WARNING
: Returns a successful lookup response with a low-match quality warningREG4NOMATCH
: Returns the VIN and vehicle description but no matching vehicleREG4VINONLY
: 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.