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 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
  },
  "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 which is contained in the vehicle’s list of supported vehicle state capabilities indicates that the corresponding property might be included in the vehicle states generated for the vehicle.

Example

A vehicle with the state capability FUEL_LEVEL_IN_PERCENT supports having a fuel_level_in_percent 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 the vehicle states generated for this vehicle.

Partial vehicle state⚓︎

If a vehicle has a certain vehicle state capability, this only 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.

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 message⚓︎

The recommended way to constantly receive the most recent vehicle state is by subscribing to the Messaging API. This way, you immediately get a message 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, for each vehicle state property supported by the particular vehicle the most recently received value is included.

If you only need to know the current state of your vehicles periodically and do not wish to subscribe to a real-time stream of vehicle state messages, the latest vehicle state might be a useful option for you.

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 Messaging 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. Contrary to the “latest vehicle state” (see above), this option does not return an existing vehicle state from a database. Instead, the INVERS OneAPI always 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 and installed telematics unit. 

  2. How often certain vehicle state properties are being transmitted/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 driving. 

  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. 

Back to top