About Our Van Carbon Footprint API

Our Van Carbon Footprint API provides a calculation of the total annual CO2 output in metric tonnes from a van powered by an internal combustion engine based upon the user's annual mileage.

For cars see our car carbon footprint API.

The carbon footprint is based on the van's CO2 output and the user's annual mileage.

Where the CO2 data is available for more than just the WLTP Combined cycle the calculator can also create a calculation based on the vehicle's mileage in each WLTP CO2 cycle (e.g. urban, suburban, rural and motorway mileage) each year.

In our sample below the display includes both the Combined cycle CO2/mileage and the additional CO2/mileage cycles

In implementation these cycles/CO2 values can all be be presented or can be presented as an either/or choice to the user.

For example, the implementation can show:

• just the Combined cycle if only Combined CO2 data is available; or
• just show the urban, suburban, rural and motorway cycles where the additional CO2 data is available; or
• show both sets of cycles (when available) so the user can benchmark against the Combined cycle and see the impact of differing levels of urban, suburban, rual and motorway driving against the total carbon footprint of the vehicle.

Dataset

There are two main datasets delivered. The first is derived from an initial request for the vehicle specifications dataset - this carries CO2 values for the vehicle.

The user then provides mileage data to allow the API to calculate the carbon footprint.

The user's mileage selections are then returned to the API with the CO2 output for a calculation of the carbon footprint in metric tonnes per annum.

For details of the vehicle selection see the Car Selection API.

For details of the vehicle specifications content see the Car Specifications API.

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 the carbon footprint data using XML.

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).

The specifications request is contained in the API instructions for that feature.

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.

The returned dataset cover the vehicle CAPID, manufacturer, model and derivative details, the user selected mileages at each CO2 cycle and the carbon footprint at that cycle in metric tonnes.

Where the urban, suburban, rual and motorway cycles are used the dataset also includes a total footprint value.

The total footprint value allows the user to compare the benchmark Combined cycle carbon footprint with the impact of the user's actual mileages within the various different cycles on the actual total carbon footprint.

{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 technical specifications list 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 published technical specifications for a vehicle - new vehicle model ranges/derivatives may not return a dataset.

Data Retrieval

Once you have selected a vehicle below add the annual mileage against each presented CO2 category and click on the 'Calculate' button to see a returned 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.

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
p_miles_c: An integer type variable for the number of miles travelled annually at the WLTP Combined cycle (effectively the annual mileage of the vehicle)
p_miles_l: An integer type variable for the number of miles travelled annually at the WLTP Low (urban) cycle
p_miles_m: An integer type variable for the number of miles travelled annually at the WLTP Medium (suburban) cycle
p_miles_h: An integer type variable for the number of miles travelled annually at the WLTP High (rural) cycle
p_miles_e: An integer type variable for the number of miles travelled annually at the WLTP Extra High (motorway) cycle
v_co2_c: An integer type variable for the CO2 output of the vehicle in grammes per kilometre at the WLTP Combined cycle
v_co2_l: An integer type variable for the CO2 output of the vehicle in grammes per kilometre at the WLTP Low (urban) cycle
v_co2_m: An integer type variable for the CO2 output of the vehicle in grammes per kilometre at the WLTP Medium (suburban) cycle
v_co2_h: An integer type variable for the CO2 output of the vehicle in grammes per kilometre at the WLTP High (rural) cycle
v_co2_e: An integer type variable for the CO2 output of the vehicle in grammes per kilometre at the WLTP Extra High (motorway) cycle