cap API Spec

Overview

cap API allows subscribers to access cap-hpi data using HTTP services. A subscriber needs to use their subscriber id and password to gain access.

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: ShortTermForecast/v1

Content Negotiation

The API will provide both JSON and XML, 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" or "application/xml" will return the requested format.

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

Example - Request


GET https://services.cap.co.uk/ShortTermForecast/v1/VehicleTypes HTTP/1.1
Host: services.cap.co.uk
Accept: application/json

Example - Response


HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 86
Connection: Close
{
    "vehicleTypes":[
        {
        "typeId": 1,
        "description": "Car",
        "abbreviation": "CAR"
        }
    ]
}

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 in to 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/XML format of arrays.

Authentication

The authentication will be token based authentication. The subscriber needs to get a token using their cap subscriber ID and password, then use this token for subsequent calls.

Description

Method Url
POST v1/Authentication

Parameters

Type Example
Authorization Header Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

The value of the basic authentication is subscriberId:password encoded in base64 encoding. This is used to generate the token, which is then stored in the database. The username and password is then no longer needed until the token expires, in which the client will need to request another token.

Response

Status Response
200 
{
  "availableProducts": "https://services.cap.co.uk/ShortTermForecast/v1/1",
  "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "tokenType": "Bearer",
  "expiresIn": "120 minutes"
}
401 
{"error": "Invalid subscriber ID or password."}
500 
{"error": "Something went wrong. Please try again later."}
Status Response
200 
<?xml version="1.0" standalone="no" ?>
<authorization>
<availableProducts>https://services.cap.co.uk/ShortTermForecast/v1/1</availableProducts>
<accessToken>eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...</accessToken>
<tokenType>Bearer</tokenType>
<expiresIn>120 minutes</expiresIn>
</authorization>
401 
<?xml version="1.0" standalone="no"?>
<error>Invalid subscriber id or password.</error>
500 
<?xml version="1.0" standalone="no"?>
<error>Something went wrong. Please try again later.</error>

The expiresIn property of the response is measured in minutes - therefore in the above example the expiry time will be 2 hours. This will expire regardless of usage. Once the token has expired the subscriber will have to request a new token to continue using the API.

Using the Access Token

You need to send your access token with every request to the API as follow:

Type Example
Authorization Header Bearer <accesstoken>

JSFiddle Example

Option Values

Get option values for cap ID and Option IDs

Returns option values data for a cap ID, mileage, option IDs and pack IDs for a specific registration date. This will return a breakdown of how much all of the options are worth in total, as well how much each individual option is worth, and whether it contributed to the overall value according to the relevant rules.

This endpoint can retrieve values for all cap condition types, however only Clean is available for 13-60 months. This is for cars only.

The option and pack IDs can be retrieved if you are subscribed to the cap NVD Web Service.

Description

Method Url
POST OptionValues/v1/Options/{CapId}

Parameters

Type Name Data Type Optional
Authorization Refer to Using the Access Token No
Body registrationDate Date No
Body mileage int No
Body conditionsRequired Array of strings. (From "Clean", "Average", "Below" or "Retail") No
Body requiredValuationMonths Array of ints (0-60) No
Body listOfOptionsIdsToValue Array of ints Must have at least one here or in listOfPackIdsToValue
Body listOfPackIdsToValue Array of ints Must have at least one here or in listOfOptionsIdsToValue

Response

Status Response
200 Note: This is part of the result. To see the full result please try jsfiddle example 
{
  "valuationDate": "2016-12-29T00:00:00",
  "rules": {
    "maxPercentOfVehiclePrice": 0.15,
    "maxNum": 5
  },
  "breakdown": [
    {
      "valuationMonth": 0,
      "cleanTotalOptionsValue": 430,
      "averageTotalOptionsValue": null,
      "belowTotalOptionsValue": null,
      "retailTotalOptionsValue": null,
      "options": [
        {
          "id": 67862,
          "name": "Front sports seats with electric side bolster adjustment",
          "costNew": 410,
          "value": 200,
          "includedInValuation": true
        },
        {
          "id": 61202,
          "name": "Metallic - Black sapphire",
          "costNew": 645,
          "value": 0,
          "includedInValuation": false
        }
           //more options
      ],
      "packs": [
        {
          "options": [
            {
              "id": 1432,
              "name": "Front sliding armrest",
              "includedInValuation": false
            },
            {
              "id": 95578,
              "name": "Versatile net",
              "includedInValuation": false
            }
            //more options within packs
          ],
          "id": 102263,
          "name": "Interior comfort pack - 4 Series",
          "costNew": 1285,
          "value": 0,
          "includedInValuation": false
        },
        {
          "options": [
            {
              "id": 70201,
              "name": "Reversing camera",
              "includedInValuation": false
            },
            {
              "id": 103552,
              "name": "Park assist gap measurement and steering assist",
              "includedInValuation": true
            }
          ],
          "id": 102256,
          "name": "Advanced parking pack - 4 Series",
          "costNew": 545,
          "value": 230,
          "includedInValuation": true
        }
        //more packs
      ]
    }
  ]
}
400 
{"message": "The request is invalid."}
401 
{"error": "Unauthorised" }
500 
{"error": "Something went wrong. Please try again later."}
Status Response
200 Note: This is part of the result. To see the full result please try jsfiddle example 
<?xml version="1.0" standalone="no"?>
<optionValues>
    <valuationDate>2016-12-29T00:00:00</valuationDate>
    <rules>
        <maxPercentOfVehiclePrice>0.15</maxPercentOfVehiclePrice>
        <maxNum>5</maxNum>
    </rules>
    <breakdown>
        <valuationMonth>0</valuationMonth>
        <cleanTotalOptionsValue>430</cleanTotalOptionsValue>
        <averageTotalOptionsValue />
        <belowTotalOptionsValue />
        <retailTotalOptionsValue />
        <options>
            <id>67862</id>
            <name>Front sports seats with electric side bolster adjustment</name>
            <costNew>410</costNew>
            <value>200</value>
            <includedInValuation>true</includedInValuation>
        </options>
        <options>
            <id>61202</id>
            <name>Metallic - Black sapphire</name>
            <costNew>645</costNew>
            <value>0</value>
            <includedInValuation>false</includedInValuation>
        </options>
        <!-- more options -->
        <packs>
            <options>
                <id>1432</id>
                <name>Front sliding armrest</name>
                <includedInValuation>false</includedInValuation>
            </options>
            <options>
                <id>95578</id>
                <name>Versatile net</name>
                <includedInValuation>false</includedInValuation>
            </options>
            <!-- more options within pack -->
            <id>102263</id>
            <name>Interior comfort pack - 4 Series</name>
            <costNew>1285</costNew>
            <value>0</value>
            <includedInValuation>false</includedInValuation>
        </packs>
        <packs>
            <options>
                <id>70201</id>
                <name>Reversing camera</name>
                <includedInValuation>false</includedInValuation>
            </options>
            <options>
                <id>103552</id>
                <name>Park assist gap measurement and steering assist</name>
                <includedInValuation>true</includedInValuation>
            </options>
            <id>102256</id>
            <name>Advanced parking pack - 4 Series</name>
            <costNew>545</costNew>
            <value>230</value>
            <includedInValuation>true</includedInValuation>
        </packs>
        <!-- more packs -->
    </breakdown>
</optionValues>

JSFiddle Example

Short Term Forecast

Short Term Forecast Options

There are a standard set of options available on every request for short term forecast valuations. These are listed below:

Name Data type Purpose
valuationDate date The valuation date of a single short term forecast snapshot. If the date supplied is not an exact match then the closest snapshot before this date will be returned
monthFrom int The number of the month to begin the short term forecast valuations from e.g. if the 1st month of a short term forecast is January and 5 is specified then the valuations returned will start from May onwards
monthTo int The number of the month to begin the short term forecast valuations from e.g. if the 1st month of a short term forecast is January and 10 is specified then the valuations returned will end at October
mileage int Restrict valuations to a single mileage point. If this is not provided then all available mileage points will be returned

These are all contained in a single parameter and separated by |. Each option value is a key value pair specified using the following pattern name:value. For example &options=monthFrom:1|monthTo:6 appended to the request will return the 1st 6 months of valuations.

Restrictions

  • All dates must be specified in ISO8601 date format e.g. 2015-08-26 would be 26th August 2015
  • monthFrom and monthTo must be integers between 1 and 12
  • monthTo cannot be greater than monthFrom
If any of the above conditions are specified the response will return a status of 400 - Bad Request with an indication of the error(s) in the body. For example, given the following options parameter: &options=monthFrom:6|monthTo:2 returns: 

{
    "optionsError": [
    "monthFrom option should be less than monthTo option. monthFrom:6, monthTo:2"
    ]
}
<version="1.0" standalone="no"?>
<optionsErrors>
    <optionsError>monthFrom option should be less than monthTo option. monthFrom:6, monthTo:2</optionsError>
</optionsErrors>

Response

Status Response
200 Note: This is part of the result. To see the full result please try jsfiddle example 
[
  {
    "valuationDate": "2015-08-21T00:00:00",
    "plates": [
      {
        "plate": {
          "yearMonth": "2010 60",
          "plateSequenceNumber": 94
        },
        "plusValues": [
          {
            "date": "2015-10-01T00:00:00",
            "mileagePoints": [
              {
                "mileage": 1,
                "clean": 10250,
                "average": 9650,
                "below": 9050
              }
                // another mileage point
             ]
           }
            // another plus value
          ]
       }
        // another plate
      ],
     "comments": [
      {
        "commentDate": "2015-10-01T00:00:00",
        "comment": "sample comment"
      }
    //another comment
  }
 ]
400 
{"message": "The request is invalid."}
401 
{"error": "Unauthorised" }
404 
{"error": "No short term forecast data found" }
500 
{"error": "Something went wrong. Please try again later."}
Status Response
200 Note: This is part of the result. To see the full result please try jsfiddle example 
<?xml version="1.0" standalone="no"?>
<shortTermForecasts>
 <shortTermForecast>
    <valuationDate>2015-08-21T00:00:00</valuationDate>
    <plates>
      <plate>
        <yearMonth>2010 60</yearMonth>
        <plateSequenceNumber>94</plateSequenceNumber>
        <plusValues>
          <plusValue>
            <date>2015-10-01T00:00:00</date>
            <mileagePoints>
              <mileage>1</mileage>
              <clean>10250</clean>
              <average>9650</average>
              <below>9050</below>
            </mileagePoints>
            <mileagePoints>
             <!-- Another mileagePoint value -->
            </mileagePoints>            
          </plusValue>
          <plusValue>
          	<!-- Another plusValue -->
          </plusValue>
        </plusValues>
      </plate>
      <plate> 
      	<!-- Another plate -->       
      </plate>   
    </plates>
    <comments>
      <comment>
        <commentDate>2015-10-01T00:00:00</commentDate>
        <editorialComment>sample comment</editorialComment>
      </comment>
      <comment>
      	<!-- Another comment -->        
      </comment>     
    </comments>
  </shortTermForecast>
  <shortTermForecast>
  	<!-- Another shortTermForecast -->     
  </shortTermForecast>
</shortTermForecasts>
400 
<?xml version="1.0" standalone="no"?>
<message>The request is invalid.</message>
401 
<?xml version="1.0" standalone="no"?>
<error>Unauthorised</error>
404 
<?xml version="1.0" standalone="no"?>
<error>No short term forecast data found</error>
500 
<?xml version="1.0" standalone="no"?>
<error>Something went wrong. Please try again later.</error>

Get Short Term Forecast for Vehicle Type ID with cap ID

Returns short term forecast data for the Vehicle Type ID route, with a cap ID. The vehicle types can be obtained by following the Get Vehicle Types route.

Description

Method Url
GET ShortTermForecast/v1/{vehicleTypeId}?{capId}&{options}

Parameters

Type Name Data Type Optional
Authorization Refer to Using the Access Token No
Query String capId int No
Query String options Refer to Short Term Forecast Options Yes

Response

Refer to response

JSFiddle Example

Get Short Term Forecast for Vehicle Type ID, cap ID, Year and Letter

Returns short term forecast data for the Vehicle Type ID route, with cap ID, year and letter (i.e. ‘T’ for a 99 plate or ‘64’ for a 2014 plate). The vehicle types can be obtained by following the Get Vehicle Types route.

Description

Method Url
GET ShortTermForecast/v1/{vehicleTypeId}/byYearLetter?{capId}&{year}&{letter}&{options}

Parameters

Type Name Data Type Optional
Authorization Refer to Using the Access Token No
Query String capId int No
Query String year int No
Query String letter string No
Query String options Refer to Short Term Forecast Options Yes

Response

Refer to response

JSFiddle Example

Get Short Term Forecast for Vehicle Type ID, cap ID, Year and Month

Returns short term forecast data for the Vehicle Type ID route, with cap ID, year and month. The vehicle types can be obtained by following the Get Vehicle Types route.

Description

Method Url
GET ShortTermForecast/v1/{vehicleTypeId}/byYearMonth?{capId}&{year}&{month}&{options}

Parameters

Type Name Data Type Optional
Authorization Refer to Using the Access Token No
Query String capId int No
Query String year int No
Query String month int No
Query String options Refer to Short Term Forecast Options Yes

Response

Refer to response

JSFiddle Example

Get Short Term Forecast for Vehicle Type ID, cap ID and Plate ID (plate sequence number)

Returns short term forecast data for the Vehicle Type ID route, with a cap ID for a specific plate sequence number. This will return a valuation for a single plate only. The vehicle types can be obtained by following the Get Vehicle Types route.

The plate sequence number can be retrieved if you are subscribed to the cap DVLA Web Service and lookup a VRM.

Description

Method Url
GET ShortTermForecast/v1/{vehicleTypeId}/byPlatedId?{capId}&{plateId}&{options}

Parameters

Type Name Data Type Optional
Authorization Refer to Using the Access Token No
Query String capId int No
Query String plateId int No
Query String options Refer to Short Term Forecast Options Yes

Response

Refer to response

JSFiddle Example

Get Short Term Forecast for Vehicle Type ID, cap ID and Registration Date

Returns short term forecast data for the Vehicle Type ID route, with cap Id and vehicle registration date. Get Vehicle Types route.

Description

Method Url
GET ShortTermForecast/v1/{vehicleTypeId}/byRegistrationDate?{capId}&{registrationDate}&{options}

Parameters

Type Name Data Type Optional
Authorization Refer to Using the Access Token No
Query String capId int No
Query String registrationDate date No
Query String options Refer to Short Term Forecast Options Yes

Response

Refer to response

JSFiddle Example

Vehicle Types

Returns a list of vehicle types

Description

Method Url
GET ShortTermForecast/v1/VehicleTypes

Parameters

Type Example
Authorization Header Please refer to using access token

Response

Status Response
200 Note: This is part of the result. To see the full result please try jsfiddle example 
[
  {
    "typeId": 1,
    "description": "Car",
    "abbreviation": "Car"
  },
  {
    "typeId": 2,
    "description": "Light Commercial",
    "abbreviation": "LCV"
  }
]
401 
{"error": "Invalid subscriber ID or password."}
500 
{"error": "Something went wrong. Please try again later."}
Status Response
200 Note: This is part of the result. To see the full result please try jsfiddle example 
<?xml version="1.0" standalone="no"?>
<vehicleTypes>
  <vehicleType>
    <typeId>1</typeId>
    <description>Car</description>
    <abbreviation>Car</abbreviation>
  </vehicleType>
  <vehicleType>
    <typeId>2</typeId>
    <description>Light Commercial</description>
    <abbreviation>LCV</abbreviation>
  </vehicleType>
</vehicleTypes>
401 
<?xml version="1.0" standalone="no"?>
<error>Invalid subscriber id or password.</error>
500 
<?xml version="1.0" standalone="no"?>
<error>Something went wrong. Please try again later.</error>

JSFiddle Example

WLTP

Overview

cap API allows subscribers to access WLTP 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

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-hpi.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

Name Type Mandatory Description
Array<derivativeConfiguration>
id string false Unique identifier of the request (if supplied by the requestor will be included in the response)
derivativeType enum [ Car, LCV ] true Unique identifier of vehicle type
capId integer true Unique identifier assigned to a vehicle derivative in the Cap system
modelYear string true Model year identifier
selectedEquipmentIds array<integer> true List of comma-separated Cap equipment IDs that are applicable to the specified derivative. These should be current and valid options

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

Name Type Mandatory Description
auditId guid true Unique transaction ID referencing the associated request (generated by the CAP system)
id guid false Request identifier that can be set (if supplied by the requester)
derivativeType enum [ Car, LCV ] true Unique identifier of vehicle type
capId integer true Unique identifier assigned to a vehicle derivative in the CAP system
modelYear string true Model year identifier
selectedEquipmentIds array<integer> true List of comma-separated Cap equipment IDs that are applicable to the specified derivative. These should be current and valid options
validUntil date true Date when the calculated values would expire
examinationDate date true Date when the WLTP data is calculated
errors Array<Error>
id integer optional Error message identifier
type string optional Error message label (e.g. Invalid_Vehicle_Configuration)
message string optional The text of the error message which would be displayed to the user
technicalSpecificationItems Array<TechnicalSpecificationItem>
id integer true Code associated to the technical data.
name string true The description of the data item associated to the code item (e.g. "WLTP – CO2 – Low")
value string true The value associated with the TechnicalSpecificationItem

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.