About Our Hybrid Car Running Costs Calculator - Outright Purchase
This version of our hybrid car running costs calculator prepares a comparison of car running costs using outright purchase.
Running costs can be analysed independently or matched with the equivalent tools for petrol, diesel and electric cars to compare running costs side by side.
The user can also compare the costs of business or personal contract hire with outright purchase.
This API produces the running costs for an hybrid powered car based upon outright purchase. Optionally the user can also view the vehicle's running costs with personal or business contract hire.
We use business contract hire and personal contract hire in the API but this can be customised to adapt for other funding methods upon request.
To calculate the running costs users:
- select an annual vehicle total mileage;
- choose a vehicle (manufacturer, range and derivative)
This will produce a whole life cost for 1 to 5 years based on forecast depreciation, maintenance and fuel costs. Optionally the costs of insurance can be added to the calculation.
Modules
The calculator uses existing modules for creating mileage and vehicle selections. See the:
You can see the requirements for those items on the respecti API help pages. This page explains the {GET} and {POST} request sequences to invoke the cost calculation API.
For the finance calculator to function your site will need facilities for the user to:
- select the vehicle
- obtain a residual value forecast (e.g. for contract hire) or post a monthly finance rental
- choose the finance term and mileage.
Optionally the API can also include the cost of user selected factory or dealer fitted options in the calculation.
You can see these in our API pages for the Car Selector and Factory Fitted Options APIs.
Dataset:
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.
The dataset comprises a series of tables with data covering:
- vehicle pricing, VED, CO2 output, etc;
- residual value and depreciation costs;
- servicing, maintenance and repair costs;
- fuel consumption and fuel costs
- optionally, insurance costs
Our Demo
Our demonstrator provides an illustration of how the API delivers an outright purchase whole life cost using XML.
We provide examples of the related HTTPS {GET}/{POST} requests for each stage of (other than those already illustrated on other API pages).
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.
{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, the car's CAPID and the annual mileage selection.
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 mileage and vehicle, in our sample API a whole life cost calculation 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.
This will include the dataset XML node descriptions so that you can see the schema.
Once you have obtained an initial response the whole life cost calculations can be updated for user selections covering:
- vehicle price
- fuel price/consumption
- insurance cost
This allows the user to customise the whole life cost calculation to their particular circumstances.
VAT
The values to be provided in the {GET} request are VAT inclusive.
To provide net of VAT values to a user divide each dataset item liable to VAT by 1.2 (assuming a VAT rate of 20%), so exclude the registration fee and VED as these items do not currently 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
This page is constructed from existing APIs plus two further API requests for the initial whole life costs calculation and an updated request for custom calculations.
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)
Vehicle
Details of the requests for creating a vehicle are as set out in the Car Selector API page.
Other
f_a_miles: an integer type variable for the annual mileage of the vehicle
v_l_price: a double type variable for the list price or price paid for the vehicle (excluding delivery etc)
v_dc_pric: a double type variable for the manufacturer's published delivery charges for the vehicle
v_r_fee: a double type variable for the initial registration fee for the vehicle
v_ved1: a double type variable for the 1st year's vehicle excise duty (tax disc)
v_otr: a double type variable for the On-The-Road Price of the vehicle
v_ved2: a double type variable for the 2nd and subsequent years' vehicle excise duty
v_f_c_f: a double type variable for the cost of fuel per litre for the vehicle in pence per litre
v_mpg: a double type variable for the average fuel consumption of the vehicle
v_tank: a double type variable for the fuel tank capacity of the vehicle in imperial gallons
v_e_o_m: a double type variable for the ratio of electric-only motoring to total annual mileage
v_f_c_e: a double type variable for the cost of fuel per kilowatt hour for the vehicle in pence per kW/H
v_b_con: a double type variable for the average battery consumption rate of the vehicle
v_b_kwh: a double type variable for the battery capacity of the vehicle in kilowatt hours
v_b_ran: an integer type variable for the battery range of the vehicle in miles
v_b_chr: a double type variable for the VAT inclusive cost of installing a home electric car charger
after any subsidies
v_i_p: a double type variable for the annual insurance premium for the vehicle