APIs/Connected Vehicle API
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 GroupEndpointResourceClassic vehicles onlyNon-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 typeWill return fuelAmountWill 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

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

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

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.

Release notes/Overview