Skip to content

Vehicle State⚓︎

The vehicle state is one of the key elements within the INVERS OneAPI: It is a hardware-agnostic description of both the vehicle’s and the installed telematics unit’s state and, thus, an integral part when you integrate with the INVERS OneAPI.

Structure⚓︎

The vehicle state contains a set of vehicle state properties which tell you something about a specific aspect of the vehicle.

Example

This example shows the structure of a vehicle state. One thing you can see is state_of_charge_or_fuel_level_in_percent, which tells you that the vehicle’s fuel level is 85%.

{
  "mileage_in_kilometers": {
    "timestamp": "2020-01-30T13:22:05Z",
    "value": 10000
  },
  "state_of_charge_or_fuel_level_in_percent": {
    "timestamp": "2020-01-30T13:22:05Z",
    "value": 85
  },
  "remaining_range_in_kilometers": {
    "timestamp": "2020-01-30T13:22:05Z",
    "value": 100
  },
  "position": {
    "timestamp": "2020-01-30T13:22:05Z",
    "value": {
      "lat": 50.834,
      "lon": 8.0219
    }
  },
  "driving_enabled": {
    "timestamp": "2020-01-30T13:22:05Z",
    "value": true
  }
  // ... (truncated)
}

Each vehicle state property has its own timestamp which tells you exactly when this information was captured by the vehicle’s telematics unit. Different vehicle state properties may have different timestamp values depending on the underlying telematics unit.

Supported properties⚓︎

When a vehicle is added to your fleet, the supported vehicle state capabilities are being determined automatically by the INVERS OneAPI depending on the vehicle model1. Each capability contained in the vehicle’s list of supported vehicle state capabilities indicates that the corresponding property might be included in vehicle states generated for the vehicle.

Example

A vehicle with the state capability DRIVING_ENABLED supports having a driving_enabled property in its vehicle states.

Consequently, if a capability is not part of the vehicle’s list of supported vehicle state capabilities, the corresponding property will never be included in any vehicle state generated for this vehicle.

Partial vehicle state⚓︎

If a vehicle has a certain vehicle state capability, this tells you that a vehicle state for that vehicle can contain the matching vehicle state property. However, the property is not necessarily included in every vehicle state of that vehicle. For example, if a vehicle has the vehicle state capability DOORS_STATUS it is not guaranteed that there is a doors_status property present in every vehicle state of that vehicle.

There are two main reasons for partial vehicle states. The first reason is that some telematics units are simply designed like this: They only transmit the properties that have changed since the last transmission of their state. Other telematics units always transmit all properties they can determine, even if they haven’t changed recently.

The second reason is outlined in the example below: Sometimes it may not be possible for the telematics unit to determine a certain vehicle state property. In such a case, it is simply omitted when an updated state is transmitted.

Example

A vehicle with the POSITION capability usually has a position property in the vehicle states it generates. However, if for example the position cannot be determined by the GPS module of the telematics unit, the position property may not be included in a particular vehicle state of the vehicle.

Get vehicle state⚓︎

There are multiple options for receiving the vehicle state of your fleet’s vehicles.

Receive vehicle state via event⚓︎

The recommended way to constantly receive the most recent vehicle state is by subscribing to the Events API of INVERS OneAPI. This way, you immediately get an event every time the vehicle transmits new data and, consequently, a new vehicle state is created.

This allows you to keep your own application(s) in sync with the actual state of your vehicles. You could store a copy of the vehicle state locally within your application, or react to changes to the vehicle immediately after they occur.

Keep in mind that you might receive partial vehicle states.

Get latest vehicle state⚓︎

In addition, the INVERS OneAPI always stores the most recently received value for each of the vehicle state properties for you. You can get this so-called “latest vehicle state” using the Vehicle Management API by calling GET /vehicles/:id/latest-vehicle-state. Therein, you can find the most recently received value for each vehicle state property supported by the particular vehicle.

If you only need to know the current state of your vehicles infrequently and do not wish to subscribe to a real-time stream of vehicle state events, the latest vehicle state might be a useful option for you (instead of the aforementioned Events API).

The INVERS OneAPI automatically updates the latest vehicle state in the background as soon as the telematics units installed in your vehicles send new information.

Warning

Use the Events API if you always want to keep your vehicle’s states in sync between OneAPI and your application. Do not frequently poll the latest vehicle state using the Vehicle Management API for this use case!

Request new vehicle state⚓︎

All important changes, e.g. changes to the vehicle’s central lock status, are usually2 transmitted instantly when they occur. However, less discrete values like the current position3 will not be sent every time they change. That is why you can directly request a new vehicle state from the vehicle by using the request-vehicle-state command of the Vehicle Commands API.

Use this option if you require a new and up-to-date version of the vehicle state in that moment. Contrary to the “latest vehicle state” (see above), this option does not return an existing vehicle state from a server. Instead, the INVERS OneAPI tries to contact the vehicle directly in order to trigger the creation of a new vehicle state that is as up-to-date as possible.

  1. The capabilities are derived from the combination of vehicle model, installed telematics unit, potential extensions / additional hardware, and configuration of the telematics unit. ↩

  2. How often certain vehicle state properties are being transmitted or updated is highly dependant on the telematics unit type. Oftentimes, this is configurable and also changes depending on whether or not the vehicle is currently unlocked and moving. ↩

  3. Transmitting a new position every time it changes would often mean that position data would be transmitted every second. This is usually not viable nor needed. ↩