Go Live checks for Vehicle Taxonomy – Auto Trader UK

To get live API access, your integration must pass certain tests. This will make sure that it meets our technical standards and best practices.

For each capability, the tests cover Essential and Enhanced functionalities. Your integration must pass at least one of the Essential functionality tests to get live access.

We recommend using the Enhanced functionalities to allow dealers to get the full benefits of the service.

We'll cover the tests for the following functionalities:

Vehicle registration lookup (Essential)
- - Vehicle MOT test data (Enhanced)
  - Vehicle history (Enhanced)
  - Vehicle charge times (Enhanced)
Taxonomy lookup (Essential)
- - Taxonomy technical data (Enhanced)
  - Taxonomy prices (Enhanced)

There are three ways we check that tests are successful:

Demonstration - We will expect you to show us your code or your UI
Call log validation - We will check your API calls to our service to make sure the call is made correctly
Database check - We will check our database to see whether the correct attribute has been updated

Vehicle registration lookup (Essential)

When looking up a vehicle via the Vehicles API, you must pass us:

The advertiser ID that the lookup is for
The registration for the vehicle

Most of our vehicle data that’s available in production will be available in sandbox for you to test with. But, newer vehicles and recent plate changes may not be.

Test	How we'll check it
Successfully get vehicle details for a registration via the Vehicles API	Call log validation
If using MOT test data, history, and charge time data, this is done all in one call to the Vehicles API. It should not be in multiple calls where possible	Call log validation
Detect failed lookups and do not retry on a schedule e.g. hourly or daily	Demonstration

Auto Trader data has great coverage but, like any service, there are instances where we may not be able to provide full data or any data at all for a vehicle.

Below are some registrations that you can use in your testing:

Test case	Response code	Test VRM(s)
No derivative ID found	200	ZZ01ABC
No first registration date found	200	ZZ02ABC
Not full vehicle data	200	ZZ03ABC ZZ04ABC (S) ZZ05ABC (N)
Malformed registration	400	A1B2C3D4
Not found	404	ABC125

Vehicle MOT test data (Enhanced)

If you need data on a vehicle’s MOT test history, you can include the motTests=true query string parameter on the Vehicles API request.

Test	How we'll check it
Successfully get MOT test data for a VRM via the Vehicles API	Call log validation and demonstration

Vehicle history (Enhanced)

If you need vehicle history data, you can include the history=true query string parameter on the Vehicles API request.

Test	How we'll check it
Successfully get history data for a VRM via the Vehicles API	Call log validation and demonstration
Optional checks
Able to identify a vehicle with a history issue if one of the following is flagged in the history object: Scrapped Stolen Imported Exported	Demonstration

Vehicle charge times (Enhanced)

If you need data on a vehicle’s charge time, you can include the chargeTimes=true query string parameter on the Vehicles API request.

Test	How we'll check it
Successfully get charge time data for a VRM via the Vehicles API	Call log validation and demonstration

Taxonomy lookup (Essential)

Alternatively, you can get base vehicle data from our Taxonomy APIs. By navigating through the vehicle types, makes, models, generations, and derivatives we have in our vehicle data, you can get a derivative ID. If you are only working with one vehicle type, e.g. cars, you could skip the 'vehicle types' call and go straight to 'makes'.

Test	How we'll check it
Able to call the Makes endpoint in the Taxonomy API to get all makes for a given vehicle type	Call log validation
Able to call the Models endpoint in the Taxonomy API to get all models for a given make ID	Call log validation
Able to call the Generations endpoint in the Taxonomy API to get all generations for a given model ID	Call log validation
Able to call the Derivatives endpoint in the Taxonomy API to get all derivatives for a given generation ID	Call log validation
All above calls to Taxonomy API contain the vehicleType parameter to prevent any duplication of results for multiple vehicle types	Call log validation
Optional checks
Able to call the vehicleTypes endpoint in the Taxonomy API to get all vehicle types	Call log validation
Able to use facet filtering (e.g. fuelType, transmissionType etc.) to filter down any of the above responses	Call log validation

To help with testing, here are a couple of examples that you may wish to use.

Please note: One example will allow you to get a derivative ID. The other will not have any generations or derivatives as we don't have the data. Make sure your system handles this and prompts the dealer accordingly.

Test case	Expected derivative ID
Vehicle Type: Car Make: Ford Model: Fiesta Generation: Hatchback (2021 - 2023) Derivative: 1.5T EcoBoost ST-3 Hatchback 5dr Petrol Manual Euro 6 (s/s) (200 ps)	19bcd23215e849068113851019593c19
Vehicle Type: Car Make: Ferrari Model: Scuderia Spider Generation: this will be an empty array	No derivative ID is available

Taxonomy technical data (Enhanced)

Once you have a derivative ID from the above APIs, you can use it to access our base vehicle data from the Taxonomy API. This will be in a similar format to what would be returned by the Vehicles API.

Test	How we'll check it
Able to get technical data from Taxonomy API for a given derivative ID	Call log validation and demonstration

Taxonomy price data (Enhanced)

With the derivative ID, you can also get price history data for that derivative. This will have the base price from the manufacturer and the delivery price of that derivative.

Test	How we'll check it
Able to get price history data from the Taxonomy API for a given derivative ID	Call log validation and demonstration