APIs/Connected Vehicle API

Release Notes

Overview

The release notes provide details about new features, breaking changes, and other updates made to the Connected Vehicle API. Hence releasing the version 2 with the following changes and additions.

New features

Additional supported models

This version of the API supports additional models for most endpoints. All car models between model year 2015 and 2022 are supported if not otherwise specified.

Endpoints with limited support

The API now provides limited support in certain endpoints, including;

API Group	Endpoint	Resource	Classic vehicles only	Non-Classic vehicles only
API Group Warnings	Endpoint warnings	Resource sideMarkLightsWarning	Classic vehicles only No	Non-Classic vehicles only Yes
API Group Warnings	Endpoint warnings	Resource hazardLightsWarning	Classic vehicles only Yes	Non-Classic vehicles only No
API Group Warnings	Endpoint warnings	Resource reverseLightsWarning	Classic vehicles only Yes	Non-Classic vehicles only No
API Group Doors, Windows and Locks	Endpoint lock-reduced-guard	Resource	Classic vehicles only No	Non-Classic vehicles only Yes
API Group Lights and sound	Endpoint honk	Resource	Classic vehicles only Yes	Non-Classic vehicles only No
API Group Lights and sound	Endpoint honk-flash	Resource	Classic vehicles only Yes	Non-Classic vehicles only No
API Group Lights and sound	Endpoint flash	Resource	Classic vehicles only Yes	Non-Classic vehicles only No
API Group Engine	Endpoint engine-start	Resource	Classic vehicles only Yes	Non-Classic vehicles only No
API Group Engine	Endpoint engine-stop	Resource	Classic vehicles only Yes	Non-Classic vehicles only No

Vehicle Details - Add Fuel type and Gear box

The Vehicle Details endpoint now have two additional data fields; Fuel type and Gear box. The values for Fuel type are:

ELECTRIC
PETROL/ELECTRIC
PETROL
DIESEL
NONE

The values for Gear box are:

AUTOMATIC
MANUAL

Fuel endpoint

The fuel endpount now also includes battery charge level. It will return fuel amount, battery charge level, or both dependent on the fuel type.

Fuel type	Will return fuelAmount	Will return batteryChargeLevel
Fuel type Diesel	Will return fuelAmount Yes	Will return batteryChargeLevel No
Fuel type Petrol	Will return fuelAmount Yes	Will return batteryChargeLevel No
Fuel type Electric	Will return fuelAmount No	Will return batteryChargeLevel Yes
Fuel type Petrol Electric	Will return fuelAmount Yes	Will return batteryChargeLevel Yes

Breaking changes

Removed Endpoints

Battery charge level

The endpoint for getting battery charge level has been removed and the data is now returned in the new consolidated endpoint for fuel.

Get sent command details

In alignment with the changes made for the command API, the previous way of fetching information about the sent command is removed. Since we now receive a response for the command made, there is no need for storing information about the sent command.

List sent commands

Similiar to the "Get sent command details" there will not be any information saved about which commands have been sent. This logic is now up to the user to save.

Send navigation point of interest

This endpoint has been discontinued in order to streamline the API and focus our efforts on delivering customer value.

Get external temperature

This endpoint has been discontinued in order to streamline the API and focus our efforts on delivering customer value.

Commands

The version 2 of the command API is synchronous and the status returned will determine the outcome of the command. The request will block for up to 150 seconds so the caller may choose to wrap the call in an asynchronous structure in their preferred language. The response structure for commands has changed. It now includes more detailed information about the executed command, such as invocation status.

Lock doors

{
  "status": 202,
  "operationId": "d91bc882-ab09-4cdf-95eb-1e52b43d06d6",
  "async": {
    "status": "RUNNING",
    "id": "2b116f42-921b-4976-b369-d3506de58a29",
    "href": "https://api.volvocars.com/connected-vehicle/v1/vehicles/{vin}/request/2b116f42-921b-4976-b369-d3506de58a29",
    "expires": "2022-03-12T13:25:21Z"
  }
}

Unlock doors

Unlock doors also include information about the readiness to unlock.

{
  "status": 202,
  "operationId": "d91bc882-ab09-4cdf-95eb-1e52b43d06d6",
  "async": {
    "status": "RUNNING",
    "id": "2b116f42-921b-4976-b369-d3506de58a29",
    "href": "https://api.volvocars.com/connected-vehicle/v1/vehicles/{vin}/request/2b116f42-921b-4976-b369-d3506de58a29",
    "expires": "2022-03-12T13:25:21Z"
  }
}

Start climatisation

{
  "status": 202,
  "operationId": "d91bc882-ab09-4cdf-95eb-1e52b43d06d6",
  "async": {
    "status": "RUNNING",
    "id": "2b116f42-921b-4976-b369-d3506de58a29",
    "href": "https://api.volvocars.com/connected-vehicle/v1/vehicles/{vin}/request/2b116f42-921b-4976-b369-d3506de58a29",
    "expires": "2022-03-12T13:25:21Z"
  }
}

Stop climatisation

{
  "status": 202,
  "operationId": "d91bc882-ab09-4cdf-95eb-1e52b43d06d6",
  "async": {
    "status": "RUNNING",
    "id": "2b116f42-921b-4976-b369-d3506de58a29",
    "href": "https://api.volvocars.com/connected-vehicle/v1/vehicles/{vin}/request/2b116f42-921b-4976-b369-d3506de58a29",
    "expires": "2022-03-12T13:25:21Z"
  }
}

Diagnostics

Engine

The response structure for engine diagnostics has been updated to provide more detailed information about engine coolant level and oil level.

{
  "status": 200,
  "operationId": "c65248ec-1c94-11eb-adc1-0242ac120002",
  "data": {
    "engineCoolantLevel": {
      "value": "LOW",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "oilLevel": {
      "value": "NORMAL",
      "timestamp": "2020-11-19T21:23:24Z"
    }
  }
}

Diagnostics

The diagnostics endpoint has been enhanced to offer additional details on service warnings, engine hours to service, kilometers to service, and months to service.

{
  "status": 200,
  "operationId": "c65248ec-1c94-11eb-adc1-0242ac120002",
  "data": {
    "serviceWarningStatus": {
      "value": "NORMAL",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "serviceWarningTrigger": {
      "value": "CALENDAR_TIME",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "engineHoursToService": {
      "value": "198",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "kmToService": {
      "value": "29958",
      "unit": "kilometers",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "monthsToService": {
      "value": "22",
      "timestamp": "2020-11-19T21:23:24Z"
    }
  }
}

Brakes

The response structure for brake diagnostics has been modified to provide brake fluid level warnings.

{
  "status": 200,
  "operationId": "c65248ec-1c94-11eb-adc1-0242ac120002",
  "data": {
    "brakeFluid": {
      "value": "NORMAL",
      "timestamp": "2020-11-19T21:23:24Z"
    }
  }
}

Doors, windows and locks

Windows

The response structure for window status has been updated to provide more details about individual windows.

{
  "status": 200,
  "operationId": "c65248ec-1c94-11eb-adc1-0242ac120002",
  "data": {
    "frontLeftWindowOpen": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "frontRightWindowOpen": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "rearLeftWindowOpen": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "rearRightWindowOpen": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24Z"
    }
  }
}

Doors and lock status

The response structure for door and lock status has been improved to provide more information about the status of different doors and components.

{
  "status": 200,
  "operationId": "c65248ec-1c94-11eb-adc1-0242ac120002",
  "data": {
    "carLocked": {
      "value": "UNLOCKED",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "frontLeftDoorOpen": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "frontRightDoorOpen": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "hood": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "rearLeftDoorOpen": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "rearRightDoorOpen": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "tailGateOpen": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "tankLidOpen": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24Z"
    }
  }
}

Engine

Engine status

The response structure for engine status has been updated to provide more details about the engine's current state.

{
  "status": 200,
  "operationId": "c65248ec-1c94-11eb-adc1-0242ac120002",
  "data": {
    "engineRunning": {
      "value": "STOPPED",
      "timestamp": "2020-11-19T21:23:24Z"
    }
  }
}

Start engine

The response structure for starting the engine has changed. It now includes more information about the operation.

{
  "status": 202,
  "operationId": "d91bc882-ab09-4cdf-95eb-1e52b43d06d6",
  "async": {
    "status": "RUNNING",
    "id": "2b116f42-921b-4976-b369-d3506de58a29",
    "href": "https://api.volvocars.com/connected-vehicle/v1/vehicles/{vin}/request/2b116f42-921b-4976-b369-d3506de58a29",
    "expires": "2022-03-12T13:25:21Z"
  }
}

Stop engine

The response structure for stopping the engine has changed, providing additional details about the operation.

{
  "status": 202,
  "operationId": "d91bc882-ab09-4cdf-95eb-1e52b43d06d6",
  "async": {
    "status": "RUNNING",
    "id": "2b116f42-921b-4976-b369-d3506de58a29",
    "href": "https://api.volvocars.com/connected-vehicle/v1/vehicles/{vin}/request/2b116f42-921b-4976-b369-d3506de58a29",
    "expires": "2022-03-12T13:25:21Z"
  }
}

Fuel

Fuel amount

The response structure for fuel amount has been updated to include more precise information about fuel levels. It will return fuel amount, battery charge level, or both dependent on the fuel type.

{
  "status": 200,
  "operationId": "c65248ec-1c94-11eb-adc1-0242ac120002",
  "data": {
    "fuelAmount": {
      "value": "47",
      "unit": "liters",
      "timestamp": "2020-11-19T21:23:24Z"
    }
  }
}

Lights and sound

Flash exterior lights

The response structure for flashing exterior lights now includes more details about the operation.

{
  "status": 202,
  "operationId": "d91bc882-ab09-4cdf-95eb-1e52b43d06d6",
  "async": {
    "status": "RUNNING",
    "id": "2b116f42-921b-4976-b369-d3506de58a29",
    "href": "https://api.volvocars.com/connected-vehicle/v1/vehicles/{vin}/request/2b116f42-921b-4976-b369-d3506de58a29",
    "expires": "2022-03-12T13:25:21Z"
  }
}

Honk horn

The response structure for honking the horn has been updated to provide additional information.

{
  "status": 202,
  "operationId": "d91bc882-ab09-4cdf-95eb-1e52b43d06d6",
  "async": {
    "status": "RUNNING",
    "id": "2b116f42-921b-4976-b369-d3506de58a29",
    "href": "https://api.volvocars.com/connected-vehicle/v1/vehicles/{vin}/request/2b116f42-921b-4976-b369-d3506de58a29",
    "expires": "2022-03-12T13:25:21Z"
  }
}

Honk and flash

The response structure for honking and flashing has changed to provide more details about the operation.

{
  "status": 202,
  "operationId": "d91bc882-ab09-4cdf-95eb-1e52b43d06d6",
  "async": {
    "status": "RUNNING",
    "id": "2b116f42-921b-4976-b369-d3506de58a29",
    "href": "https://api.volvocars.com/connected-vehicle/v1/vehicles/{vin}/request/2b116f42-921b-4976-b369-d3506de58a29",
    "expires": "2022-03-12T13:25:21Z"
  }
}

Odometer

The response structure for odometer readings has been updated to provide more accurate unit information.

{
  "status": 200,
  "operationId": "c65248ec-1c94-11eb-adc1-0242ac120002",
  "data": {
    "odometer": {
      "value": "23554",
      "unit": "kilometers",
      "timestamp": "2020-11-19T21:23:24Z"
    }
  }
}

Statistics

The response structure for vehicle statistics, including average fuel consumption and average speed, has been enhanced with more precise unit information.

{
  "status": 200,
  "operationId": "c65248ec-1c94-11eb-adc1-0242ac120002",
  "data": {
    "averageFuelConsumption": {
      "value": "18.2",
      "unit": "liters",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "averageSpeed": {
      "value": "14",
      "unit": "kilometers_per_hour",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "tripMeter1": {
      "value": "222",
      "unit": "kilometers",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "tripMeter2": {
      "value": "0",
      "unit": "kilometers",
      "timestamp": "2020-11-19T21:23:24Z"
    }
  }
}

Tyres

Tyre status

The response structure for tyre status has been updated to provide more specific warnings about individual tyres.

{
  "status": 200,
  "operationId": "c65248ec-1c94-11eb-adc1-0242ac120002",
  "data": {
    "frontLeft": {
      "value": "NORMAL",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "frontRight": {
      "value": "NORMAL",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "rearLeft": {
      "value": "NORMAL",
      "timestamp": "2020-11-19T21:23:24Z"
    },
    "rearRight": {
      "value": "NORMAL",
      "timestamp": "2020-11-19T21:23:24Z"
    }
  }
}

Vehicles

List vehicles

The response structure for listing vehicles has been updated to provide more accurate information.

{
  "status": 200,
  "operationId": "b24cbfc8-5d20-41b4-b77b-340a6b3bb36f",
  "data": [
    {
      "vin": "XXXZWA8T1K1000147"
    }
  ],
  "pagination": {
    "limit": 1,
    "total": 1
  }
}

Vehicle details

The response structure for retrieving vehicle details has been enhanced with additional details about gearbox and fuel type.

{
  "status": 200,
  "operationId": "9d955266-ce84-43c4-8da2-159361349df5",
  "data": {
    "modelYear": "2019",
    "vin": "XXXZWA8T1K1000147",
    "externalColour": "SAVILE GREY",
    "images": {
      "exteriorDefaultUrl": "https://cas.volvocars.com/image/vbsnext-v4/exterior/MY19_1817/225/A8/13/49200/R131/_/TP02/_/_/TM02/JT02_f13/SR02/_/_/JB0C/T206/default.png?market=us&client=connected-vehicle-api&w=1920&bg=00000000&angle=0&fallback",
      "interiorDefaultUrl": "https://cas.volvocars.com/image/vbsnext-v4/interior/MY19_1817/225/1/RC0000_f13/NC04/DI02/RU06/_/_/FJ01/EV02/K502/default.png?market=us&client=connected-vehicle-api&w=1920&bg=00000000&angle=0&fallback"
    },
    "descriptions": {
      "model": "V60 II",
      "upholstery": "CHARCOAL/LEAC/CHARC",
      "steering": "LEFT"
    }
  }
}

Warnings

The response structure for vehicle warnings has been updated to provide more detailed information about various warning indicators.

{
  "operationId": "c65248ec-1c94-11eb-adc1-0242ac120002",
  "status": 200,
  "data": {
    "bulbFailure": {
      "timestamp": "2020-11-19T21:23:24Z",
      "value": "MULTIPLE"
    }
  }
}

Common response model

The fields status and operationId are removed from the common response model but are still available as HTTP status and HTTP header VCC-API-OperationId.

Resource models

Content type headers

Content type header is now always application/json. This is done to simplify API consumption. Version is now always defined in the API URL path.

Accept headers

Accept header is now always application/json. This is done to simplify API consumption. Version is now always defined in the API URL path.