About Our Electric Van Mileage Home Charging Calculator

This API allows users to calculate company van mileage reimbursement rates for electric vans for 'Home' charging.

'Home' charging can involve costs such as the standing charge for electricity, the cost per kiloWatt-hour of electricity, the installation cost of a home charger, etc.

We cover these variations in the costs in this API calculator. To see 'Away' charging (which has a different cost structure) click on this link.

HM Revenue & Customs ('HMRC') does not provide indicative company van mileage reimbursement rates (as compared to company cars under the Advisory Fuel Rate system).

Reimbursement is therefore subject to the generic rules for expenses reimbursements to employees.

Employers who reimburse company van drivers for the costs of recharging should keep records of how the electricity costs are calculated.

Typically these records should show the costs incurred by the employee (such as 'home' electricity bills) for the cost per kilowatt-hour (kWh) and any other standing charges incurred.

To calculate the reimbursement costs in this API users;

• choose a vehicle (manufacturer, range and derivative);
• confirm the battery kWh capacity and range;

Then, for 'home' charging;

• confirm whether or not standing charges will be reimbursed;
• the cost of electricity; and
• the percentage of the driver's electricity bill appropriate to recharging^*.

This calculator will then produce the reimbursement rate required for the driver.

^*The percentage of the employee's home electricity bill appropriate to electric van charging is required for HMRC purposes. Typically, employees can only claim a tax deductions for business related mileage costs.

Modules

The calculator uses existing modules for creating the vehicle selections. See the Van Selector API.

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;

• the selected vehicle (manufacturer, model and derivative);
• cost of recharging including standing charges, connection/subscription fees and cost per kWh; and
• the resulting reimbursement rate required for the driver (in pence per mile).

Our Demo

Our demonstrator provides an illustration of how the API delivers a mileage reimbursement rate 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 driver's selections for 'home' or 'away' costs of electricity.

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 sample API a reimbursement rate 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 calculations can be updated for user selections covering:

• vehicle data
• fuel prices/consumption rates
• the mileage reimbursement rate

The mileage reimbursement rate takes account of the selections made for the vehicle and any updated variables such as standing charge, percentage of electricity bill for electric vehicle charging, etc.

This allows the user to customise the reimbursement calculation to their particular circumstances.

VAT

The values to be provided in the {GET} request are VAT inclusive for 'home' charging.

This is because the supply of electricity to a driver at home involves a supply to the driver, rather than the employer, and VAT is typically rated at only 5% for domestic electricity (compared to 20% for electricity supplied to businesses).

Even if the driver's employer reimburses the driver for the cost of 'home' recharging the employer cannot recover the VAT on the cost of the electricity supplied to the driver.

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 for selecting a vehicle, plus a further API request for the initial mileage rate calculation.

Once the initial request is made for a mileage calculation an updated request can be made using custom calculations based on changes to the standard assumptions (e.g. cost of electricity, battery range, etc).

The initial request for a calculation should be submitted to:

'https://api.drivesmart.uk//Electric_Van_Mileage_Home_DataSet'

The subsequent changes to variables should be submitted to:

'https://api.drivesmart.uk//Electric_Van_Mileage_Home_Update_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)

Vehicle

Details of the requests for creating a vehicle are as set out in the Car Selector API page.

Other
On selection of the vehicle the API will produce standard data on the mileage rate for the vehicle and additional variables created from the calculation.

The user can then adjust the variables used in the calculation by re-submitting the request with some/all of the following variables:

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_f_c: a double type variable for the cost of fuel per kilowatt hour for the vehicle in pence per kW/H
v_b_kwh: a double type variable for the battery capacity of the vehicle in kilowatt hours
v_b_con: a double type variable for the battery consumption rate of the vehicle in kWh per mile
v_b_chr: a double type variable for the VAT inclusive cost of installing a home electric vehicle charger after any subsidies
v_b_chr_a: a double type variable for the annualised cost of installing a charger ('v_b_chr' amortised over 5 years, e.g. 'v_b_chr' ÷ 5)
v_b_c_inc: a string type variable ('Y' or 'N') for indicating if the charger cost should be included in the mileage rate calculations
v_b_chr_c: a calculated double type variable for the cost of refuelling the battery at 100%
v_b_chr_i: a string type variabe ('Y' or 'N') for indicating if the standing charge should be included in the mileage rate calculations
u_e_sc: a double type variable for the daily standing charge for the provision of electricity to the driver
u_e_pbill: a double type variable for the percentage of the employee's electricity bill which relates to charging the electric vehicle
u_a_miles: an integer type variable for the driver's total annual miles travelled in the electric vehicle
u_b_miles: an integer type variable for the driver's total business miles travelled in the electric vehicle

Worked example of both API requests are included below.