About The Electric & Hybrid Car Search API

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

• Electric Cars & Hybrids: Including battery range, recharge times, battery warranty and drivetrain configuration;
• 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.
• Monthly Payment: Including factors such as the finance type, term and annual mileage;

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

The electric cars search API can find cars by:

• battery range (WLTP range for fully electric cars, 'all-electric' range for hybrids);
• recharge time to 80% of maximum charge capacity in minutes by a 7kW ('fast') charger*;
• drive type (front wheel, rear wheel, 4 wheel drive);
• motor type (electric only, self-charging hybrid, plug-in hybrid);
• acceleration and top speed;
• BHP and torque;
• battery warranty (months and miles);
• Manufacturer/model range.

*We have used data for a 7kW 'fast' charger as this is typically the maximum charge rate for a charger installed in a UK home. Typical capacity limitations in a domestic property (80-100amps maximum total current load) restrict the supply of 'single phase' electricity to around 7kW.

When no vehicles match any of the selected criteria an empty table is returned.

In addition to individual criteria the API can display the data across all criteria for a manufacturer's models or a specific model range. Simply select a manufacturer (optionally with model range and propulsion type) to see the data across all criteria.

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 (acceleration, top speed, etc) to see a list of cars matching the requirements.

The HTTPS {GET} request for each variation in the criteria selection are given once the search is initiated.

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
• an unformatted table to display the dataset results
• a sample XML dataset for the table

Within each returned dataset we include all the performance search criteria irrespective of those selected so that the end-user can further refine the search locally.

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

d_type: xml or json for the required return data type (json if not specified)
target: The string 'EHC' to define the type of search (electric or hybrid cars)
Optional: v_e_ranl: An integer type variable to define the lower battery range
Optional: v_e_ranu: An integer type variable to define the upper battery range
Optional: v_e_chgs: A string type variable to define the charger speed from the following:

"N" - No selection (default setting)
"W" - Slow
"F" - Fast
"R" - Rapid
"S" - Super-fast

We recommend disabling the text boxes for selecting the recharge time unless a charger type is selected.

Optional: v_e_chgl: An integer type variable to define the lower charge time to 80% battery power on the seelcted charger
Optional: v_e_chgu: An integer type variable to define the upper charge time to 80% battery power on the selected charger
Optional: v_p_bhpl: An integer type variable to define the lower range for engine BHP
Optional: v_p_bhpu: An integer type variable to define the upper range for engine BHP
Optional: v_p_torl: An integer type variable to define the lower range for engine torque
Optional: v_p_toru: An integer type variable to define the upper range for engine torque
Optional: v_p_secl: A double type variable to define the lower 0-62 time in seconds/decimal parts of a second e.g. 5.5 - when selected the minimum value is 0.1

Optional: v_p_secu: A double type variable to define the upper 0-62 time in seconds/decimal parts of a second e.g. 5.5 - when selected the minimum value is 0.1

Optional: v_p_mphl: An integer type variable to define the lower range of top speed in miles per hour
Optional: v_p_mphu: An integer type variable to define the upper range of top speed in miles per hour
Optional: v_fuel: A string type variable to define the type of motor for the car from the following:

"R" - Range-extender Hybrid - Petrol
"A" - Range-extender Hybrid - Diesel
"H" - Self-charging Hybrid - Petrol
"Y" - Self-charging Hybrid - Diesel
"X" - Plug-in Hybrid - Petrol
"Z" - Plug-in Hybrid - Diesel
"E" - Fully Electric

Not all of the above are currently in use - these have been included for forwards compatibility with new propulsion types

Optional: v_drivetrain: A string from "F" (front wheel drive) or "R" (rear wheel drive) or the integer 4 (4 wheel drive)
Optional: v_e_wmill: An integer type variable to define the lower range of the manufacturer's mileage warranty for the battery
Optional: v_e_wmilu: An integer type variable to define the upper range of the manufacturer's mileage warranty for the battery
Optional: v_e_wmonl: An integer type variable to define the lower range of the manufacturer's warranty for the battery in months
Optional: v_e_wmonu: An integer type variable to define the upper range of the manufacturer's warranty for the battery in months
Optional: v_mfr: A string type variable to define a manufacturer (from our Car Selector API)
Optional: v_mod: A string type variable to define the manufacturer's model range (from our Car Selector API) Optional: v_body: A string type variable to define the vehicle body style (from our Car Search Body Style API)