About Our Van Residual Value API
Our Van Residual Value API provides the CAP-HPI forecast residual value for a van for a specified term and mileage for around 6,000 new vans currently for sale in the UK.
CAP-HPI Residual Values
CAP-HPI provides us with forecast residual values for vans ranging at 12 month intervals from 12 to 60 months and from 10,000 to 200,000 total miles (CAP-HPI residual value forecasts are always denominated in total miles irrespective of the term involved).
For example, a CAP-HPI value is provided for 24 months and 20,000 total miles - this is the equivalent to 10,000 miles per annum.
This results in a comprehensive matrix of residual value forecasts, but these may not necessarily relate directly to an annual mileage requirement.
For example, 8,000 annual miles over 5 years will directly reflect the forecast residual value for 60 months and 40,000 total miles in the CAP-HPI published residual value forecasts.
However, it will not match a data point on the matrix for any other period (e.g. 3 years @ 8,000 annual miles equates to 32,000 total miles, which is not a data point - the nearest is 36 months and 30,000 total miles).
CAP-HPI provides an interpolation formula to deal with intermediate data points between its pubished values and we apply that formula to non-published term/mileage combinations.
If you request a residual value for a term/mileage combination which is not at a set data point in the matrix the result will therefore always be an interpolation.
The value may, therefore, appear abnormal, in that it may not be rounded to a numerical value in accordance with typical data point values (e.g. typically rounded to £100, £50 or £25 values) - interpolations may be to integers in the nearest £1, e.g. £23 rather than £25.
Dataset
The dataset provides the CAP-HPI forecast residual value for a selected car.
The content of the returned dataset is:
- the CAPID sent in the {GET} request;
- the manufcturer, model and derivative associated with the CAPID;
- the term and mileage combination requested; and
- an 'integer' type value for the car's forecast residual value at the specified term and mileage (interpolated when appropriate).
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 residual values for vans using XML.
To obtain the CAP-HPI forecast residual value of a vehicle, from the list boxes below just:
- choose a manufacturer, model and derivative;
- select the finance term and annual or total mileage; then
- click the 'Residual' button.
We will display the relative HTTPS {GET} requests for each stage of car, term and mileage 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 actual {GET} request for a car's residual value only requires our standard security login/session token, the car's CAPID, the term and the annual contract mileage or the total contract mileage.
The manufacturer, range and model name are not required, 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 a published residual value for a vehicle - new vehicle model ranges/derivatives will not return a dataset until CAP-HPI publishes a value.
Data Retrieval
Once you have selected a vehicle, term and mileage below click on the 'Residual' 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.
The returned dataset for the residual value also provides manufacturer/model/derivative verification and the chosen term and mileage.
VAT
The values provided in the dataset are VAT inclusive.
To calculate the VAT exclusive equivalent residual value divide the relevant dataset value by 1.2.
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 van not discontinued
term: a valid finance term in months as an integer from 12 to 60
either
annualmiles: a number of annual contract miles for the finance agreement as an integer from 10000 to 40000 annual miles
or
totalmiles: the total number of miles for the finance agreement as an integer from 10000 to 200000 total miles
(if both the total and annual miles are provided the total miles overrides the annual miles if the values do not agree over the finance term)
Our API will convert the annual miles to a total contract miles for the term.
Where the equivalent total mileage is not a multiple of 10,000 miles the residual value returned in the dataset will be an interpolation of the main CAP-HPI dataset matrix.