About Our Car Tax Disc API
Our Car Tax Disc API calculates the annual vehicle excise duty (VED) for a car over a selected replacement cycle or finance term.
Typically this is used in tools such as our running costs calculator and our 'Lease or Buy?' and 'Cash or Company Car?' analysers, but it can also be used as a stand-alone tool to compare the annual tax disc of vehicles as VED is based on CO2 output.
Dataset
The dataset provides the tax disc cost each year of a selected replacement cycle or finance term.
The content of the dataset is a 'double' type value for the annual tax disc each year during the replacement cycle, plus the manufacturer, range and derivative, vehicle CO2 output in Grammes Per Kilometre (integer) and the CAP-HPI 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.
As the dataset relies on a CO2 output to calculate the tax disc no results will be provided unless a current CO2 output is available from CAP-HPI.
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 the annual tax disc for cars using XML.
To obtain the tax disc cost for a vehicle just choose a manufacturer, range and model from the list boxes below and then select a term/replacement cycle.
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 VED 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.
As the dataset relies on a CO2 output to calculate the tax disc a dataset will only be provided where CAP-HPI has a published WLTP CO2 output for a vehicle - new vehicle model ranges/derivatives may not return a dataset.
Data Retrieval
Once you have selected a vehicle and chosen a term/replacement cycle a dataset will be returned (if you change the car manufacturer/range/model the request will reset and you will need to select a replacement cycle again to see a new dataset).
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 VED provides each individual year's VED component calculated for the vehicle.
VAT
Currently the annual tax disc does not attract output VAT so the values provided in the dataset are VAT exclusive.
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
f_term: an integer for the replacement cycle/finance agreement term denominated in months as multiples of 12 (e.g. 12, 24, 36, 48 and 60)