WLTP API version 1 Specification

Overview

WLTP API allows subscribers to access cap-hpi data using HTTPS services.

API Version

The current version is 1. All requests should go through this version unless a new version is released. The version is specified in the API route like this: /v1

Authentication

The API uses Client Credentials Flow for authentication in order to obtain an access token using a form encoded POST The endpoint described below should be used for the access token request:

POST https://identity.cap-hpi.com/connect/token 

Example Request

{
  "client_id": "[your client ID]",
  "grant_type": "client_credentials",
  "client_secret": "[your client secret]",
  "scope": "CapHpi.Wltp.Api"
}

Request Parameters

Example Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
  "expires_in": 36000,
  "token_type": "Bearer"
}

Authenticate your account when using the API by including an access token in your request.
The access token is passed in as a bearer token via the authorization request header:

Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng

Content Negotiation

The API will provide JSON, based on the Accept header received from the client. JSON will be returned if an Accept header is not provided. All valid requests, with a value of "application/json" will return the requested format.

All requests must be made over HTTPS, any requests made over HTTP will return an error message.

Data Types

Fundamentals

Fundamental data types are provided as typically expected. A string is wrapped in double quotes, an integer (or int) is provided as a whole number, a double is provided with a decimal place. Non-standard data types are covered in the next section.

Structs

Date

A date is provided as a string to the API, but must be provided in the ISO 8601 format for year, month and date (YYYY-MM-DD).

For example, the 21st July 2015 would be represented as a string in the format: 2015-07-21.

Arrays

Sometimes many values need to be requested from the API, and this may need to be done as part of an array. If these are required, they will be part of a POST request, and will be part of the BODY of the request and will be made up of the other data types. These will conform to the JSON format of arrays.

WLTP Requests

Request for WLTP values for one or more vehicle derivatives

This service is used to retrieve WLTP emissions values for a specified vehicle.
To get WLTP data for derivative POST the values below to the WLTP endpoint:

POST https://api.cap.co.uk/v1/wltp 

Example Request

[
  {
    "id": "72f6e102-a2ac-437f-a70c-f2beef736fc0",
    "derivativeType": "Car",
    "capId": 84106,
    "modelYear": "2018",
    "selectedEquipmentIds": [
      517, 682
    ]
  },
  {
    "id": "77c5ch05-3d35-4297-9d5b-f721d6a24568",
    "derivativeType": "Car",
    "capId": 81135,
    "modelYear": "2019",
    "selectedEquipmentIds": [
      444
    ]
  }
]
                            

Request Parameters

Example Response

{
  "auditId": "4097a739-cc87-466d-ac67-3a3ead6fb5a4",
  "errors": [],
  "wltpData" : [
    {
      "id": "72f6e102-a2ac-437f-a70c-f2beef736fc0",
      "validUntil": "2018-07-19T10:55:19Z",
      "examinationDate": "2018-07-18T10:55:19Z",
      "derivativeType": "Car",
      "capId": 84106,
      "modelYear": "2018",
      "selectedEquipmentIds": [
        517, 682
      ],
      "errors": [],
      "technicalSpecificationItems": [
        {
          "id": 170,
          "name": "WLTP - CO2 (g/km) - Combined",
          "value": 135
        },
        {
          "id": 181,
          "name": "WLTP - MPG - Low Speed",
          "value": 39.8
        }
      ]
    },
    {
      "id": "77c5ch05-3d35-4297-9d5b-f721d6a24568",
      "validUntil": "2018-07-19T10:55:19Z",
      "examinationDate": "2018-07-18T10:55:19Z",
      "derivativeType": "Car",
      "capId": 81135,
      "modelYear": "2019",
      "selectedEquipmentIds": [
        444
      ],
      "errors": [
        {
          "id": 10004,
          "name": "derivative_not_found",
          "message": "The vehicle with specified CAP ID was not found in the new vehicle database."
        }
      ],
      "technicalSpecificationItems": []
    }
  ]
}
                            

Response Properties

Open API

Below is a preview of the open API extract in JSON format prepared for ease of use by development teams:

Click here to download the JSON file.