About Our Car Comparator

This API retrieves a dataset for a specifed car so you can compare it with other cars.

For our multi-vehicle comparison click on this link.

The dataset allows you to compare:

• Prices (list price, delivery charges, 1st and 2nd/subsequent year VED, registration fee and on-the-road price)
• Technical specifications (emissions, M.P.G., top speed, battery performance, etc)
• Standard equipment (interior and exterior trim, etc)
• Options and option prices (no-cost and at-cost)

The returned dataset is more detailed than the multi-vehicle comparison and allows the user to see data elements behind the summaries presented in the multi-vehicle comparator.

The dataset also includes a template for comparison of each data item with other cars.

Dataset

Data can be provided as 'JSON' or 'XML' datasets and you can choose the type of data returned in your HTTPS request by declaring 'json' or 'xml' in the 'd_Type' element of the request string.

JSON is the default type for the dataset if no 'd_Type' is set.

The dataset comprises the following tables:

• 'Table_Price'
• 'Table_Technical'
• 'Table_S_E_O_Compare'
• 'Table_Equipment'
• 'Table_Options'
• 'Table_Equipment_And_Options'

'Table_Price' comprises the following:

• vehicle CAPID
• vehicle manufacturer
• model range
• model derivative
• list price
• delivery charges
• initial registration fee; and
• vehicle excise duty for the year of registration and subsequent years.

'Table_Technical' comprises all the available technical code data for the selected model including the:

• technical code for the data item
• narative description of the item
• the data type (integer "I", string "S", boolean "B" or float "F")*
• the data as a float/integer, string or boolean value

*The data type indicates which column in the table (float, string or boolean) to use to find the relevant data.

The table allows the comparison of vehicles by technical specification such as CO2 output, fuel consumption, battery range, etc.

'Table_S_E_O_Comparison' comprises a representation of certain equipment and options available for the vehicle within generic classes covering features for:

• 'Comfort'
• 'Safety'
• 'Security'
• 'Entertainment'
• 'Interior'
• 'Exterior'

The status of each item of equipment or option is represented as:

• '-': not currently recorded by CAP-HPI as available for the vehicle
• '': currently recorded as standard equipment or a default 'no-cost' option
• '£n': currently recorded as a cost option*

*Prices displayed in the table may include the cost of a required option pack if the option is not available individually.

Alternative representations of equipment and option status (e.g. '' instead of '' or '£n') are available by subscription.

Supplementary tables with the detail behind 'Table_S_E_O_Comparison' ae provided as follows:

'Table_Equipment' comprises the standard equipment for the selected vehicle including the:

• individual equipment code
• narative equipment description
• generic group code for the equipment (if applicable)

Items of equipment (or options) may be listed more than once where the item comprises a composite of other equipment/options.

Where this happens the individual component generic code for each element in the equipment/option will be shown.

For example, an airbag set may include driver, passenger and side airbags.

The set will therefore appear three times, once for each generic code for driver airbag, passenger airbag and side airbag.

'Table_Options' comprises the factory fitted options available for the selected vehicle including the:

• individual option code
• narative option description
• pre-VAT price of the option
• VAT on the option price
• generic group code for the option (if applicable)*

*Not applicable to every item (e.g. for manufacturer/range/model specific items which do not fall into a generic classification group).

'Table_Equipment_And_Options' comprises the combined equipment and factory fitted options available for the selected vehicle including the:

• individual option code
• narative option description
• pre-VAT price of the option
• VAT on the option price
• total VAT-inclusive option price
• option status (true if a default option, false if not)*
• generic group code for the option (if applicable)**

*This indicates if the option is automatically selected for the vehicle build (unless specifically deselected or overridden by another option selection).

Our Demo

Our demonstrator provides an illustration of how the API delivers the dataset for a vehicle using XML.

Each delivered table from the dataset is set out but the only required tables for vehicle comparisons are 'Table_Price', 'Table_Technical' and 'Table_Comparison'.

The individual HTTPS {GET}/{POST} requests for each stage of selecting a vehicle are explained in our API for vehicle selection.

The actual HTTPS {GET}/{POST} request for the comparison dataset is also set out.

We normally provide an example of the raw dataset but for the sake of brevity only the actual tables are displayed here.

You can copy and paste the sample request string into a browser address bar to see the raw XML data returned for the request (right click on the browser page displayed and you will see the XML dataset).

You can also substitute XML for JSON when you perform the 'copy|paste' exercise.

Implementation

We suggest that the comparator is implemented as:

• icon style data points for factors such as CO2 output, fuel consumption and battery range
• a chart/table for standard equipment/options

In either implementation charts can utilise the narrative description columns from each of the principal tables ('Table_Price', 'Table_Technical' and 'Table_S_E_O_Comparison') to provide a descriptive list or can be adapted as required.

We can also provide customised classification tables for each category of technical specification/equipment/option so that items can be grouped in an alternative manner.

{GET} Requirements

The {GET} request follows standard HTTPS key:value pair protocols. No response will be given for an HTTP request.

The {GET} request requires our standard security login/session token and the car's CAPID.

Our example obtains a valid CAPID - if you use your own method of selecting a vehicle you must provide a CAPID for a vehicle currently for sale new in the UK - a CAPID for a discontinued model or retired derivative will not return a dataset.

If our APIs are being used to create the vehicle (manufacturer, range, model, options etc) a return dataset will only be provided where CAP-HPI has a already published vehicle dataset - new vehicle model ranges/derivatives may not return a dataset.

Data Retrieval

Once you have selected a vehicle, in our example API a dataset will be provided automatically using the sample {GET} request provided below.

You will also see the {GET} request string as an example and the returned dataset structured as a typical online representation of XML for the car.

The individual dataset XML node descriptions can be seen by copying and pasting the {GET} request to a browser window and right clicking on the returned page to view the dataset.

Security

A session token is created on initial login and must be included as a cookie with all HTTPS requests or the request will fail.

If the user's browser does not allow functional cookies then the {GET} request will become orphaned and the request cannot be linked to any other requests in the same session.

If the session token is not included then the session will be terminated, any data created in the session may be erased at the server and the user may need to re-authenticate with a new session.

For security reasons the HTTPS protocol must be used for all {GET} requests so that all data passed between the browser and the server is encrypted, including the session token.

Pair:Value Summary

This page is constructed from existing APIs plus one further API request for the dataset.

Details of the API URL string components are as follows:

All
d_type: xml or json for the required return data type (json if not specified)
CAPID: the vehicle's CAP ID code (an integer only)