About Our Car Price API
Our Car Price API provides details of manufacturers' prices for each model derivative for around 6,000 new cars currently for sale in the UK.
Dataset
The dataset provides the price for a selected car derivative including the manufacturer's:
- published VAT inclusive list price
- delivery charges
- initial registration fee
- 1st and 2nd Year Vehicle Excise Duty (VED or 'tax disc')
- On-The-Road Price
- CO2 output
- fuel type
- RDE2 emissions status
- CAP-HPI fuel type code.
Fuel type and RDE2 status are automatically taken into account when calculating VED.
Optionally, the API can calculate the impact on VED from the addition of factory fitted options, including the effect of the price of the options and the CO2 output.
At the moment the options price and CO2 output must be entered manually - we already have an API for option selection and pricing and we will will shortly have a further API to calculate the additional CO2 from factory fitted options.
The content of the dataset is 'double' type values except for the CO2 output (integer) and fuel type code (string).
The dataset can be provided in 'JSON' or 'XML' format. 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.
Our Demo
Our demonstrator provides an illustration of how the API delivers prices for cars using XML.
To obtain the price of a vehicle just choose a manufacturer, then a range and model from the list boxes below.
We will display the relative HTTPS {GET} requests for each stage of car selection; you can copy and paste the sample request strings 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.
As each vehicle model selection is made the returned dataset in our demo also includes the vehicle derivative's CAP-HPI ID code ('CAPID'), manufacturer, range and model name for verification.
{GET} Requirements
The {GET} request follows standard HTTPS key:value pair protocols. No response will be given for an HTTP request.
The {GET} request for a car's price only requires our standard security login/session token and the car's CAPID.
The manufacturer, range and model name are not required for the calculation, but these items will be returned as part of the dataset for verification purposes.
The CAPID must be for a vehicle currently for sale new in the UK - a CAPID for a discontinued model or retired derivative will not return a dataset.
A dataset will only be provided where CAP-HPI has a published manufacturer's list price for a vehicle - new vehicle model ranges/derivatives may not return a dataset.
Similarly, a WLTP CO2 value for the car derivative is required to calculate Vehicle Excise Duty (the 'tax disc'), so a full dataset will only be provided where CAP-HPI has a published a WLTP CO2 value for the vehicle derivative.
Data Retrieval
As you make your selections for the vehicle manufacturer, model and derivative the price table will be updated automatically.
You will also see the entire {GET} request string as an example and the returned dataset structured as a typical online representation of XML for the car.
This will include the dataset XML node descriptions so that you can see the schema.
The returned dataset for price provides the individual price components as published by CAP-HPI.
Once you've gone through the selection process you can also see a sample implementation of the price list.
Click on the 'View Sample Implementation' button to open a new browser window with a sample web display page.
VAT
The values provided in the dataset are VAT inclusive.
To calculate the VAT exclusive equivalent values for the list price and delivery charges divide the relevant dataset values by 1.2 (exclude the registration fee and VED as these items do not attract VAT).
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
d_type: xml or json for the required return data type (json if not specified)
CAPID: valid CAPID for a car not discontinued
o_price: double type value for the cost of options
o_co2: integer value for the additional CO2 value of factory fitted options