The Comcar API uses HMAC authentication

Each request will require the following data to be sent in the headers:

• nonce - a random cryptographic nonce
• time - an integer time stamp (unix time, seconds since 1st January 1970)
• key - your api key, provided by us
• hash - a SHA256 hash based on the request properties

The hash is made up of the following elements:

• your api key
• message body (see below)
• your api secret
• the random nonce
• the current unix timestamp

The above items are concatenated in that order, converted to lowercase and then encrypted with SHA256
The message body is made up of key/value pairs of any GET parameters sent in the request, put into alphabetical order, eg:

    // message body key/values pairs
    params = {
        apples: 5,
        bananas: 7,
        cherries: 4
    }
    message_body_to_hash="apples=5bananas=7cherries=4"

Examples of how to access the API from some common technologies will be shown below, including how to build the HMAC authentication code.

Following these guides you should be able to access the API from any programming language or environment, provided you have your API key and API secret, the ability to create a SHA256 hash and make an https request.

    #!/bin/bash

    # Setup required variables
    host="api.comcar.co.uk"
    path="/v1/vehicles/makes/lamborghini/models/aventador/vehicles/"
    api_key="YOU_API_KEY"
    api_secret="YOU_API_SECRET"
    nonce="CREATE_A_UUID"
    timestamp=$(date -u +%s)

    # concat variables for ease of use
    hmac_key="$api_key$api_secret$nonce$timestamp"
    # get the sha256 hash of the concatted vbls
    # only return first 64 characters as the rest of the output is unnecessary
    hmac=$( echo -n "$hmac_key" | tr '[:upper:]' '[:lower:]' | sha256sum | head -c 64  )

    # make the request, adding the necessary headers
    # add i to the flags to include headers in output
    curl https://{$host}${path} \
            -H "hash: $hmac" \
            -H "key: $api_key" \
            -H "nonce: $nonce" \
            -H "time: $timestamp" \
            -H "x-timestamp: $timestamp" | \
    # pipe the output to python's JSON pretty printer
            python -m json.tool

Our API is developed using the Postman API IDE, the generated documentation includes an authentication script you can use to get started with Postman

Add the script to your postman collection, or as a "Pre-request Script", making sure you have setup the environment variables used in the script. Postman authenticaion

A complete list of API endpoints can be found here: V1 Endpoint Documentation

The Quick Start section contains a guide on how to use some of the endpoints to build a company car tax calculator

When requesting data from the API in JSON, you may need to paginate the data. This is done using the query string parameter page to specify the page you wish to retrieve.

The size of the page can also be specified using page_size. Please refer to the complete documentation here for further information. The default page size is 100.

Some endpoints support further filtering on the results. Please see the full documentation on the available filter options for each endpoint.

v1 is a major upgrade from the previous v0.X versions, and includes a number of additional features and breaking changes. This section is provided to document those.

Fields renamed

Response fields

In the /vehicles/vehicle endpoint a number of fields have been renamed to be more concise and include units of measurement where appropriate.

The emissions.co2 field has been replaced with 4 new fields:

• nedc_co2_gpkm
• wltp_co2_gpkm
• wltp_co2_gpkm_tel
• wltp_co2_gpkm_teh

The _tel/_teh suffixed figures give you the possible WLTP range of CO₂ emissions for the vehicle, based on selected optional equipment.
Heavier options will push the CO₂ value closer to the _teh limit, but it will never go above. Lighter options tend towards _tel

nedc_co2_gpkm is there for reference, the figures will empty out as we stop getting updates for NEDC figures. When historic vehicles are made available their NEDC figures will be shown.

Request fields

The tax modifiers on the api.comcar.co.uk/vehicles/vehicle end point have been renamed to all be prefixed with tax_ for clarity:

• capital_contribution → tax_capital_contribution
• payment_for_private_use → tax_payment_for_private_use
• taxable_option_cost → tax_taxable_option_cost

Please see example responses for further information.

Subdomain prefixes dropped

vehicles.api.comcar.co.uk/ → api.comcar.co.uk/vehicles/
prices.api.comcar.co.uk/ → api.comcar.co.uk/prices/

CSV format has been removed

The option of requesting the results as CSV via `format=csv` has been removed. This was due to performance limitations.
Please contact us if you require a custom export of our data in a CSV format.

Pagination has been updated

The following fields in the response have been updated:
page_token has been renamed to page
results has been renamed to total_count
next_page_token is no longer valid.

Only the request to the first page will return the total_count and page_count fields. Once you've sent a request to the first page, you can use these values to paginate the remainder of the results.

• WLTP (Worldwide Harmonised Light Vehicle Test Procedure)
  We have added a variety of new fields to accommodate the new way of measuring CO₂ emissions and fuel consumption.
  (teh and tel stand for Test Energy High and Test Energy Low respectively. Which is the highest and lowest configurable weight for the vehicle).
  Please refer to www.wlftpfacts.eu for more information on WLTP.
  These have been added to the api.comcar.co.uk/vehicles/vehicle end point
  
  Added to the vehicle emissions struct:
  
  • wltp_co2_gpkm - CO₂ grams per kilometre
  • wltp_co2_gpkm_tel - CO₂ grams per kilometre (Test Energy Low)
  • wltp_co2_gpkm_teh - CO₂ grams per kilometre (Test Energy High)
  
  Added to the vehicle economy struct:
  
  • mpg_low_tel miles per gallon at low speed (Test Energy Low)
  • mpg_medium_tel miles per gallon at medium speed (Test Energy Low)
  • mpg_high_tel miles per gallon at high speed (Test Energy Low)
  • mpg_extra_high_tel miles per gallon at extra high speed (Test Energy Low)
  • mpg_low_teh miles per gallon at low speed (Test Energy High)
  • mpg_medium_teh miles per gallon at medium speed (Test Energy High)
  • mpg_high_teh miles per gallon at high speed (Test Energy High)
  • mpg_extra_high_teh miles per gallon at extra high speed (Test Energy High)
• include can now be specified as a parameter on the api.comcar.co.uk/vehicles/vehicle endpoint.
  Available values are images and equipment.
  These can be combined in a single request like so: include=images,equipment
  
  Specifying 'images' will return an image struct along with the vehicle object which will include a default 'model' & 'grade' image for the vehicle
  Specifying 'equipment' will include an equipment struct with all the options and standards available for the vehicle.
• Additional tax modifiers
  Two new tax modifiers can now be specified making a request to the api.comcar.co.uk/vehicles/vehicle endpoint.
  
  • tax_override_co2
  • tax_override_battery_range
  These can be used when you want to recalculate the tax based values from additional options (please see above on how to obtain options/equipment). For example if you have added several options that may affect the CO₂ you can calculate the total then pass this in using the tax_override_co2 parameter Note: you can omit the include parameter.
• price_type can now be specified as a parameter on the api.comcar.co.uk/prices/search endpoint.
  Available values are cheapest, in_stock and dealer_offer, which similar to above can be combined in a single request price_type=cheapest,in_stock,dealer_offer which would only return the cheapest in stock vehicle which is also on offer.
• Prices can now be filtered on make & model. e.g. &make=ford&model=fiesta
• lease_company_equipment_interest_rate is now returned by the api.comcar.co.uk/prices/search endpoint.
  This shows the monthly interest rate per option calculated on the reducing balance.
• lease_company_equipment_percentage_cost_adjustment is now returned by the api.comcar.co.uk/prices/search endpoint.
  Shows the discount percentage applied to list price of financed options.

For further information and example requests, please refer to the postman documentation here https://documenter.getpostman.com/view/3327718/SzS4SSvu

If you require further data outside of the API schema, get in touch and we will be able to provide you with an export or download which you can consume to fit your needs.