About Our Multi-Car Comparator

This API retrieves a dataset for a group of cars (up to 10) so you can compare them side-by-side on data.

The comparison uses a series of key comparative data points for each car based on pricing, technical data and standard equipment/options.

For our more detailed individual 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 and options* (classified by comfort, safety, security, entertainment and interior/exterior fitments)

*Cost and no-cost options are included according to the above classifications.

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 with data for each selected car:

• 'Table_Price'
• 'Table_Technical'
• 'Table_S_E_O_Compare'

'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 technical data for each selected model including the:

• technical code for the data item
• narative description of the item
• the data

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

The API can provide a filtered dataset (key technical data such as performance, emissions and MPG/battery performance) - this is the default - or the full dataset to allow the user to select the data to be compared.

'Table_S_E_O_Comparison' comprises a comparison of the equipment and options available for each vehicle by 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.

Our Demo

Our demonstrator provides an illustration of how the API delivers the dataset for a group of up to 10 vehicles using XML.

Each delivered table from the dataset is set out in the demo.

The individual HTTPS {GET}/{POST} requests for each stage of selecting a vehicle for inclusion in the comparison 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 tables 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 each car's CAPID.

Our example obtains valid CAPIDs for each vehicle selected. If you use your own method of selecting a vehicle you must still 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.

Duplicate CAPID's included in the {GET} request will be removed automatically, but we recommend that you prevent users from selecting the same vehicle more than once.

In each returned dataset the individual table data columns for each car are denoted by their CAPID.

Data Retrieval

Once you have selected a a group of vehicles, 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 the existing APIs for vehicle selection to obtain the CAPID for each vehicle plus one further API request for the dataset for the selected cars.

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)
v_c_com: a string variable representing the vehicle CAPID codes (an integer only) for each vehicle required in the dataset (maximum 10) with each CAPID separated by a hyphen ('-'), e.g. v_c_com=12345-56789-98765.
d_t_set: a string variable comprising 'all' in lower case to provide the entire technical dataset - as a default a filtered and grouped dataset is provided if this paramater is not set - any other entry for this parameter is ignored