DriveSmart APIs: Electric Car Mileage Away Charging Calculator



About Our Electric Car Mileage Away Charging Calculator

This API allows users to calculate company car mileage reimbursement rates for electric cars for 'Away' charging.

'Away' charging can involve costs such as a subscription to the charger company, a fee per charge and the cost per kiloWatt-hour of electricity.

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

HM Revenue & Customs ('HMRC') provides indicative company car mileage reimbursement rates under the Advisory Fuel Rate system for petrol, diesel, LPG and electric cars.

Hybrid cars are treated according to the primary fossil fuel type for the vehicle. For example, a company car with a petrol combustion engine and an electric motor will be teated at the appropriate petrol reimbursement rate.

This API calculates the cost of fuel for an electric car according to the electricity charges incurred by the user for charging when away from home, such as at a commercial charging station.

The rates published by HMRC are based on historical data on electricity costs during the appropriate last quarter but apply forward, normally starting from the quarter days of 1 March, 1 June, 1 September and 1 December each year.

Because the rates published by HMRC are only 'advisory', employers can alternatively pay other mileage rates for electric company cars based upon the costs incurred by the company car driver or based upon the employer's forecast of electricity costs.

Employers who pay rates other than those published by HMRC should keep records of how the electricity costs are calculated.

Typically these records should show the costs incurred by the employee for the cost per kilowatt-hour (kWh) and any other standing charges incurred, etc.

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 'away' charging;
  • confirm whether or not connection fees will be reimbursed;
  • confirm whether or not any subscription fees will be reimbursed; and
  • the cost of electricity per kWh.
This calculator will then produce the reimbursement rate required for the driver assuming a charge from 20% of capacity to 80% of capacity (this is the typical recommended charge to maintain battery condition).

Where the user amends the forecast range for the vehicle this can also be recalculated.

Modules

The calculator uses existing modules for creating the vehicle selections. See the Car Selector API for electric vehicles.

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 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 connection fee/subscription, the cost of electricity for 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 'away' charging.

This is because the supply of electricity to a driver or business involves a supply typically rated for VAT at 20%.

For 'away' charging the costs in the dataset can be divided by 1.2 for 'net of VAT' values where the employer can recover the 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 for selecting an electric vehicle.

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_Car_Mileage_Away_DataSet'

The subsequent changes to variables should be submitted to:

'https://api.drivesmart.uk//Electric_Car_Mileage_Away_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_fee_t: a string type variable ('C', 'M' or 'N') for indicating if there is a one-off connection fee for the charge ('C'), a monthly subscription fee for accesing the charger ('M') or no fee for accessing the charger ('N') - the default is 'N'
v_fee_c: a double type variable for indicating any charge for accessing the charger (e.g. the monthly subscription or one-off charge)
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_ran: an integer type variable for the 'real world' battery range of the vehicle in miles
v_b_con: a double type variable for the battery consumption rate of the vehicle in kWh per mile
v_b_chr_c: a calculated double type variable for the cost of refuelling the battery from 20% to 80% (current recommended EV charge to preserve battery)
u_a_miles: an integer type variable for the driver's total annual miles travelled in the electric vehicle (used when the 'real world' range is invoked)

Worked example of both API requests are included below.



 



Select a manufacturer to see the range and model lists updated, with a calculation provided for each selection of a derivative of the vehicle

Manufacturer