About The Monthly Payment Car Search API

Our search APIs allow users to look for cars meeting criteria such as:

• Monthly Payment: Including factors such as the finance type, term and annual mileage;
• Company Cars: Including P11D value, CO2 output, annual or monthly benefit and tax;
• Performance: Including top speed, acceleration, BHP and engine configuration;
• Equipment & Features: Including factors such as standard equipment and zero cost options;
• Price: Including factors basic and on-the-road price;
• Body Style: Including factors such as fuel type, seats, gearbox and fuel type.
• Electric Cars: Including factors such as battery range and recharge time;

The APIs can be combined to produce searches by factors such as company car tax and body style or battery range.

The monthly payment search API can operate from either:

• a set of tables covering monthly finance payments according to term and mileage for each finance type; or
• actual calculation of the monthly finance payment according to finance type, term and mileage and factors such as the vehicle purchase price and residual value.

In the demo API below we use the complete finance calculation including interest rate, vehicle purchase price and residual value.

This approach normally requires an additional database of vehicle purchase terms and any applicable adjustments to residual values, but for simplicity in the demo we have used the full manufacturer's list price and standard CAP-HPI residual value forecasts according to vehicle age and mileage.

Dataset

Data can be provided as 'JSON' or 'XML' datasets and 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 car search API works using XML.

Set the criteria for the search (finance type, payment term, annual mileage (product dependent) and monthly budget) to see a list of cars matching the requirements.

You can use our existing Car Finance API to create the controls for the finance type, term, payment plan and mileage or use your own within the following requirements:

• Finance type: As below for the key:value pairs
• Finance term: In our demo 12, 24, 36, 48 or 60 months but custom APIs are available with other term periods
• Finance plan: Term appropriate repayment plan from 1 to 11 months as advance payment (we use the finance API to create the plan)
• Annual mileage: In 5,000 mile increments from 10,000 to 30,000 annual miles but custom APIs are available with other annual mileages

We have set out our demo with a structured approach to each phase of the search request, adding criteria likely to be dependent on each preceding selection.

The relative HTTPS {GET} requests are available in the Car Finance API for each stage of the criteria selection; this page gives the final {GET} request for the actual search using all the selected criteria.

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.

For our returned datasets we have provided:

• a table formatted to provide a display similar to a typical end-user experience
• an unformatted table to display the dataset results
• a sample XML dataset for the table

The dataset also includes the CAPID of each vehicle which then allows a link to data on individual vehicles from other APIs.

{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 search requires only our standard security login/session token and search parameters according to the pair:value keys below.

All of the keys set out below are independent and can be used individually or in conjunction with other keys to build selection criteria for a car which meet the user's requirements.

The keys from each search can also be combined to create more sophisticated searches, e.g. body style by monthly payment, performance by body style, etc.

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

All d_type: xml or json for the required return data type (json if not specified)
f_type: A string type variable representing the type of finance from the following list:

Value	Represents
CH	Business Contract Hire
CP	Business Contract Purchase
HP	Business Hire Purchase
FL	Business Finance Lease
BL	Business Balloon Lease
PCH	Personal Contract Hire
PCP	Personal Contract Purchase
PHP	Personal Hire Purchase

Finance Rate and Plan
f_term: an integer type variable for the finance term in months (e.g. 12, 24, 36, 48, 60). Any number of months can be used from 1 to 60 but the demo is locked to 12 month intervals from 1 -5 years
f_plan: an integer type variable for the number of advance payments from 1 to 12 (e.g. 3 for '3+35' or 9 for '9+23')
f_min: an integer type variable for the minimum monthly payment for the car
f_max: an integer type variable for the maximum monthly payment for the car (the demo is locked to the upper value from the 'Budget' list box)
The f_min and f_max variables are fixed for demo purposes, linked to the selections in the demo 'Budget' list box

Optional - finance dependent
f_c_type: a string type variable for the customer type from either 'b' for business or 'p' for personal
f_rate: a double type variable for the interest rate (e.g. 4.9) - this is locked in our demo at '4.9%' and cannot be adjusted for demo purposes)
Note that the 'f_rate' variable is not required where an existing rate table of monthly payments is used
f_oh: a double type variable for a monthly finance overhead either instead of, or in addition to, the interest rate (e.g. 10.50)
Note that the 'f_oh' variable is not required where an existing rate table of monthly payments is used and is not used in our demo
f_a_miles: an integer type value for the number of annual contract miles for mileage dependent business or personal finance (e.g. contract hire, contract purchase, etc). The demo mileages are fixed at 5,000 intervals starting at 10,000 and rising to 30,000 annual miles
f_vaton: an integer type variable for the VAT status of the month payments displayed for lease funding from either '1' (VAT inclusive) or '2' (VAT exclusive)
f_vatrate: a double type variable for the VAT rate percentage applicable to the monthly payments displayed for lease funding (currently 20.0 is used in our demo to represent '20%' and cannot be adjusted for demo purposes)

Details of other possible key:value pairs for the finance search are available on request. Custom pairs can also be created.