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 car models for most endpoints. All models between model year 2015 and 2022 are supported if not otherwise specified.

Endpoints with limited support - The API now provides limited support for certain endpoints, for example:

  • Warnings - get warnings.
  • Doors, Windows and Locks - lock doors with reduced guard.
  • Lights and sound - honk horn, honk and flash, flash exterior lights.
  • Engine - start engine, stop engine.

Read more about the limitation on respective endpoint.

Vehicle details - add Fuel type and Gear box

The Vehicle details endpoint now have two additional data fields; Fuel type and Gear box.

  • Fuel type values: ELECTRIC, PETROL/ELECTRIC, PETROL, DIESEL, NONE.
  • Gear box values: AUTOMATIC, MANUAL.

Breaking changes

General

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

Removed endpoints

  • Fuel - get 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.
  • Climate - get external temperature - The endpoint for getting the external temperature has been removed.
  • Commands - 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.
  • Commands - 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.
  • Navigation - send navigation point of interest - This endpoint has been discontinued in order to streamline the API and focus our efforts on delivering customer value.

Updated endpoints

Climate - Start climatisation

{
  "data": {
    "vin": "<your-vin>",
    "invokeStatus": "COMPLETED",
    "message": ""
  }
}

Climate - Stop climatisation

{
  "data": {
    "vin": "<your-vin>",
    "invokeStatus": "COMPLETED",
    "message": ""
  }
}

Diagnostics - Get engine diagnostic values

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

{
  "data": {
    "engineCoolantLevelWarning": {
      "value": "TOO_LOW",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "oilLevelWarning": {
      "value": "SERVICE_REQUIRED",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
  }
}

Diagnostics - Get diagnostic values

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

{
  "data": {
    "serviceWarning": {
      "value": "NORMAL",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "serviceTrigger": {
      "value": "CALENDAR_TIME",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "engineHoursToService": {
      "value": "198",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "distanceToService": {
      "value": "29958",
      "unit": "km",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "timeToService": {
      "value": "22",
      "unit": "days",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
  }
}

Diagnostics - Get brake fluid level

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

{
  "data": {
    "brakeFluidLevelWarning": {
      "timestamp": "2020-11-19T21:23:24.123Z",
      "brakeFluid": "NO_WARNING"
    }
  }
}

Doors, windows and locks - Lock doors

{
  "data": {
    "vin": "<your-vin>",
    "invokeStatus": "COMPLETED",
    "message": ""
  }
}

Doors, windows and locks - Unlock doors

Unlock doors also include information about the readiness to unlock.

{
  "data": {
    "vin": "<your-vin>",
    "invokeStatus": "COMPLETED",
    "message": "",
    "readyToUnlock": false,
    "readyToUnlockUntil": 0
  }
}

Doors, windows and locks - Get windows status

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

{
  "data": {
    "frontLeftWindow": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "frontRightWindow": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "rearLeftWindow": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "rearRightWindow": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
  }
}

Doors, windows and locks - Get 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.

{
  "data": {
    "carLocked": {
      "value": "UNLOCKED",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "frontLeftDoor": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "frontRightDoor": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "hood": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "rearLeftDoor": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "rearRightDoor": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "tailGate": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "tankLid": {
      "value": "CLOSED",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
  }
}

Engine - Get engine status

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

{
  "data": {
    "engineStatus": {
      "value": "STOPPED",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
  }
}

Engine - Start engine

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

{
  "data": {
    "vin": "<your-vin>",
    "invokeStatus": "COMPLETED",
    "message": ""
  }
}

Engine - Stop engine

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

{
  "data": {
    "vin": "<your-vin>",
    "invokeStatus": "COMPLETED",
    "message": ""
  }
}

Fuel - Get 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.

{
  "data": {
    "fuelAmount": {
      "value": "47.3",
      "unit": "l",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "batteryChargeLevel": {
      "value": "87.3",
      "unit": "%",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
  }
}

Lights and sound - Flash exterior lights

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

{
  "data": {
    "vin": "<your-vin>",
    "invokeStatus": "COMPLETED",
    "message": ""
  }
}

Lights and sound - Honk horn

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

{
  "data": {
    "vin": "<your-vin>",
    "invokeStatus": "COMPLETED",
    "message": ""
  }
}

Lights and sound - Honk and flash

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

{
  "data": {
    "vin": "<your-vin>",
    "invokeStatus": "COMPLETED",
    "message": ""
  }
}

Odometer - Get odometer value

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

{
  "data": {
    "odometer": {
      "value": "23554",
      "unit": "km",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
  }
}

Statistics - Get statistics

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

{
  "data": {
    "averageFuelConsumption": {
      "value": 7.2374,
      "unit": "l/100km",
      "timestamp": "2023-11-02T19:01:48.604Z"
    },
    "averageFuelConsumptionAutomatic": {
      "value": 7.4732,
      "unit": "l/100km",
      "timestamp": "2023-11-02T19:01:48.604Z"
    },
    "averageSpeed": {
      "value": 50,
      "unit": "km/h",
      "timestamp": "2023-11-02T19:01:48.604Z"
    },
    "averageSpeedAutomatic": {
      "value": 66,
      "unit": "km/h",
      "timestamp": "2023-11-02T19:01:48.604Z"
    },
    "tripMeterManual": {
      "value": 500.0,
      "unit": "km",
      "timestamp": "2023-11-02T19:01:48.604Z"
    },
    "tripMeterAutomatic": {
      "value": 420.0,
      "unit": "km",
      "timestamp": "2023-11-02T19:01:48.604Z"
    },
    "distanceToEmpty": {
      "value": 1312,
      "unit": "km",
      "timestamp": "2023-11-02T19:01:48.604Z"
    }
  }
}

Tyres - Get tyre status

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

{
  "data": {
    "frontLeft": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "frontRight": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "rearLeft": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    },
    "rearRight": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
  }
}

Vehicle - List vehicles

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

{
  "data": [
    {
      "vin": "<your-vin>"
    }
  ],
  "pagination": {
    "limit": 1,
    "total": 1
  }
}

Vehicle - Get vehicle details

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

{
  "data": {
    "modelYear": "2019",
    "vin": "<your-vin>",
    "gearbox": "AUTOMATIC",
    "fuelType": "DIESEL",
    "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 - Get warnings

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

{
  "data": {
    "brakeLightLeftWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "brakeLightCenterWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "brakeLightRightWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "fogLightFrontWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "fogLightRearWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "positionLightFrontLeftWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "positionLightFrontRightWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "positionLightRearLeftWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "positionLightRearRightWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "highBeamLeftWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "highBeamRightWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "lowBeamLeftWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "lowBeamRightWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "daytimeRunningLightLeftWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "daytimeRunningLightRightWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "turnIndicationFrontLeftWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "turnIndicationFrontRightWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "turnIndicationRearLeftWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "turnIndicationRearRightWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "registrationPlateLightWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "sideMarkLightsWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "hazardLightsWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
    "reverseLightsWarning": {
      "value": "NO_WARNING",
      "timestamp": "2020-11-19T21:23:24.123Z"
    }
  }
}

/