INVERS Vehicle Messages
INVERS Developers

Vehicle Messages (1.0)

The Vehicle Messages interface is intended for INVERS customers who need programmatic access to integrate their applications with the INVERS platform.

Contact link: INVERS GmbH

Vehicle Messages API

The Vehicle Messages API describes messages which you can subscribe to in order to get "live updates" whenever changes to a connected vehicle's vehicle state happens: As soon as new data from a connected vehicle is received, it is instantly forwarded to your application. ​

Setup

Before consuming messages you first have to setup "Message Subscription Configuration" for your fleet and subscribe to message topics. ​

By doing so you have the required connection data for connecting to your RabbitMQ using the AMQP protocol. ​

Learn more

Message Format

JSON

The messages' payloads are returned as JSON (application/json). ​

Date Time

Date and time values are in UTC in the following ISO 8601 compatible format: 2014-10-17T08:30:00Z

Headers

The following headers are included when consuming each message: ​

  • Flow-ID
  • Message-Type
  • Message-Version

Their values are equal to their corresponding properties within the metadata properties of the message. They are included to assist in deserialization of the message within your application. ​

Vehicles and "Vehicle State"

Vehicles

The INVERS API is centered around connected vehicles. Vehicles are addressed and identified by an ID (vehicle_id). This ID is artificially generated by the system. Messages for a vehicle will only be published, if a telematics unit has been installed in the vehicle and the onboarding process was done correctly. ​

Vehicle State

A vehicle state is published whenever a vehicle sends information about its state. The vehicle state provides information about the current state of the vehicle and the installed telematics unit. The vehicle state consists of hardware agnostic data, that is independent of the installed telematics unit. ​

The presence of information depends on which data is provided by the vehicle at a certain time. Therefore, it may differ from vehicle state to vehicle state and depends on the vehicle (e.g. a scooter will not report a value for the status of the doors). ​

To reflect this reality, there is capability category called "vehicle state capabilities". Vehicle state capabilities describe that the vehicle is capable of delivering a value for the data field. For each property in the hardware agnostic vehicle state, there is a corresponding vehicle state capability. Using GET /vehicles/{vehicle_id} of the Vehicle and Telematics Management API, the list of vehicle state capabilities can be requested and may include the following vehicle state capabilities:

  • FUEL_LEVEL_IN_PERCENT
  • TOP_CASE_LOCK
  • TOP_CASE_LID
  • POSITION
  • REMAINING_RANGE_IN_KILOMETERS
  • DRIVING_ENABLED
  • IGNITION
  • CENTER_STAND_POSITION
  • MILEAGE_IN_KILOMETERS
  • CELLULAR_SIGNAL_QUALITY
  • CENTRAL_LOCK
  • ALTITUDE_IN_METERS
  • DOOR_STATUS

As a result, the properties present in a vehicle state depend on the vehicle state capabilities of that vehicle. ​

For instance, if the vehicle has the vehicle state capability TOP_CASE_LOCK, the property top_case_lock can be present in the vehicle state. However, it doesn't have to be. If it is not possible to gather information about the top_case_lock at a certain time, the field will be absent from the vehicle state.

Note that vehicle state property names are in snake_case (e.g. top_case_lock), while the vehicle state capabilities are written in UPPER_SNAKE_CASE (e.g. TOP_CASE_LOCK).

Servers

api.invers.com:5671 amqps 0.9.1

Production RabbitMQ

Operations

Sub VehicleState_v1-{queue_discriminator}

This queue holds VehicleStateReceived messages of all vehicles your fleet's vehicles. VehicleStateReceived messages will be published to this queue as soon as new information about a connected vehicle are received.

Parameters
queue_discriminator
required
string

Arbitrary value. The full queue name will be given to you during message subscription configuration.

Accepts the following message:

VehicleStateReceived_v2.0 VehicleStateReceived_v2.0

Message with information about the 'VehicleState'

released

This message will be published whenever a vehicle sent information and these are translated into a 'vehicle state'.

The vehicle state provides information about the current state of the vehicle and the installed telematics unit. The vehicle state consists of hardware agnostic data, that is independent of the installed telematics unit. The presence of information depends on which data is provided by the vehicle at a certain time. Therefore, it may differ from vehicle state to vehicle state.

Certain vehicles together with the telematics unit do not provide all data fields, e.g. a scooter will not report a value for the status of doors but a car might. To reflect this reality, there is capability category called 'vehicle state capabilities'. Vehicle state capabilities describe the data fields for which the vehicle can deliver a value. For each property in the hardware agnostic part of the vehicle state, there is a corresponding vehicle state capability. Using GET /vehicles/{vehicle_id} of the Vehicle and Telematics Management API, the list of vehicle state capabilities can be requested.

As a result, the properties present in a vehicle state depend on the vehicle state capabilities of that vehicle. For instance, if the vehicle has the vehicle state capability TOP_CASE_LOCK, the property top_case_lock can be present in the vehicle state. However, it doesn't have to be. If it is not possible to gather information about the top_case_lock at a certain time, the field will be absent from the vehicle state.

Note that vehicle state property names are in snake_case (e.g. top_case_lock), while the vehicle state capabilities are written in UPPER_SNAKE_CASE (e.g. TOP_CASE_LOCK).

Please note that it is possible to receive messages which have an empty vehicle_state: In this case, there has been contact with the vehicle but no additional data has been sent.

Payload
object
metadata
required
object

Carries metadata for a Message along with common fields.

message_id
required
string
ulid

Identifier of this message.

message_type
required
string

The name of the MessageType of this Message.

occurred_at
required
string
date-time

When the message was created according to the producer.

version
required
string

Version of the schema used for validating this message. This may be enriched upon reception by intermediaries. This string uses semantic versioning.

flow_id
string

A flow-id for this message (corresponds to the X-INVERS-Flow-ID HTTP header).

Additional properties are allowed.

data
required
object
vehicle_id
required
string
length <= 12 length >= 5

The unique ID of the vehicle.

received_at
required
string
date-time

UTC timestamp when the state was received.

fleet_id
required
string
length <= 12 length >= 5

The unique ID of the fleet the vehicle belongs to.

triggered_by
object

Describes what triggered the reception of a vehicle state.

channel
required
string

Name of the channel that was used to trigger the reception of a vehicle state.

Specification Extensions:

x-extensible-enum
[
  "BLUETOOTH",
  "API_COMMAND"
]
correlation_id
required
string

If channel is bluetooth this property includes the ID of the bluetooth token that was used to communicate with the vehicle and therefore, triggered the vehicle state. If channel is api_command this property includes the X-INVERS-Flow-ID of the API command that triggered the vehicle state.

Additional properties are allowed.

vehicle_state
required
object

The vehicle state shows the current state of the vehicle and the telematics unit installed in it. At certain times, information about a vehicle state property is not provided by the vehicle and therefore it will not be shown in the vehicle state data. In addition, when a vehicle lacks a certain vehicle state capability, the corresponding property will not be included in the vehicle state data of the vehicle.

altitude_in_meters
object allOf

Altitude of the vehicle.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
number
int32

Altitude in meters.

cellular_signal_quality
object allOf

Indicates how strong the signal of the celluar connection is.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
number
int32 >= 0 <= 5

Value between 0 - 5, where 5 is the highest quality.

center_stand_position
object allOf

Position of the center stand.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
string

Either RETRACTED or EXTENDED.

Specification Extensions:

x-extensible-enum
[
  "RETRACTED",
  "EXTENDED"
]
central_lock
object allOf

State of the central lock.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
string

Can either be LOCKED or UNLOCKED.

Specification Extensions:

x-extensible-enum
[
  "LOCKED",
  "UNLOCKED"
]
doors_status
object allOf

Status of the doors, either OPEN when at least one door is open or CLOSED if all doors are closed.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
string

OPEN when at least one door is open or CLOSED if all doors are closed.

Specification Extensions:

x-extensible-enum
[
  "OPEN",
  "CLOSED"
]
driving_enabled
object allOf

Whether you can start the engine of the vehicle.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
boolean

True means you can start the vehicle. False means you cannot.

fuel_level_in_percent
object allOf

Fuel level of the vehicle in percent (can also be state of charge for electric vehicles).

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
number
int32 >= 0 <= 100

Percentage ranging from 0 to 100.

ignition
object allOf

A vehicle has the vehicle state capability "ignition" only if the vehicle requires the driver to manually disable the ignition. The intended use is for it to indicate whether the disable_driving command should be sent. One might want to check this condition to determine whether a rental can be ended. In particular, one might want to prevent a rental from being ended unless ignition = off.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
string

Either ON or OFF.

Specification Extensions:

x-extensible-enum
[
  "ON",
  "OFF"
]
mileage_in_kilometers
object allOf

How far the vehicle has driven in total. Measured in kilometers.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
number
double >= 0

Measured in kilometers.

position
object allOf

Position of the vehicle.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
object

Position of vehicle (GPS/GLONASS/...).

lat
required
number
double >= -90 <= 90

Latitude of the position.

lon
required
number
double >= -180 <= 180

Longitude of the position.

Additional properties are allowed.

remaining_range_in_kilometers
object allOf

An estimate of how far the vehicle can drive with the remaining fuel or battery charge in kilometers.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
number
double

Measured in kilometers.

top_case_lid
object allOf

State of the top case lid.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
string

Either OPEN or CLOSED.

Specification Extensions:

x-extensible-enum
[
  "OPEN",
  "CLOSED"
]
top_case_lock
object allOf

State of the top case lock.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
string

Can either be LOCKED or UNLOCKED.

Specification Extensions:

x-extensible-enum
[
  "LOCKED",
  "UNLOCKED"
]

Additional properties are allowed.

Additional properties are allowed.

Additional properties are allowed.

Examples

VehicleStateReceived_v2.0
Payload
{
  "metadata": {
    "message_id": "01F1FHJ7SHQK5MGF69B8K2346E",
    "message_type": "ConnectedVehicles.VehicleStateReceived",
    "occurred_at": "2020-01-30T13:22:05Z",
    "version": "2.0.0",
    "flow_id": "804f2161-a15c-420f-8f21-61a15c320f68"
  },
  "data": {
    "vehicle_id": "JQ7RP",
    "received_at": "2020-01-30T13:22:05Z",
    "fleet_id": "F48XD",
    "triggered_by": {
      "channel": "API_COMMAND",
      "correlation_id": "804f2161-a15c-420f-8f21-61a15c320f68"
    },
    "vehicle_state": {
      "altitude_in_meters": {
        "timestamp": "2021-03-08T10:29:00Z",
        "value": 413
      },
      "cellular_signal_quality": {
        "timestamp": "2021-03-08T10:29:00Z",
        "value": 3
      },
      "center_stand_position": {
        "timestamp": "2021-03-08T10:29:00Z",
        "value": "EXTENDED"
      },
      "central_lock": {
        "timestamp": "2021-03-08T10:29:00Z",
        "value": "LOCKED"
      },
      "doors_status": {
        "timestamp": "2021-03-08T10:29:00Z",
        "value": "CLOSED"
      },
      "driving_enabled": {
        "timestamp": "2021-03-08T10:29:00Z",
        "value": true
      },
      "fuel_level_in_percent": {
        "timestamp": "2021-03-08T10:29:00Z",
        "value": 42
      },
      "ignition": {
        "timestamp": "2021-03-08T10:29:00Z",
        "value": "ON"
      },
      "mileage_in_kilometers": {
        "timestamp": "2021-03-08T10:29:00Z",
        "value": 100.25
      },
      "position": {
        "timestamp": "2021-03-08T10:29:00Z",
        "value": {
          "lat": 50.123,
          "lon": 7.321
        }
      },
      "remaining_range_in_kilometers": {
        "timestamp": "2021-03-08T10:29:00Z",
        "value": 242.32
      },
      "top_case_lid": {
        "timestamp": "2021-03-08T10:29:00Z",
        "value": "CLOSED"
      },
      "top_case_lock": {
        "timestamp": "2021-03-08T10:29:00Z",
        "value": "LOCKED"
      }
    }
  }
}
This example has been generated automatically.

Messages

#1 VehicleStateReceived_v2.0 VehicleStateReceived_v2.0

Message with information about the 'VehicleState'

released

This message will be published whenever a vehicle sent information and these are translated into a 'vehicle state'.

The vehicle state provides information about the current state of the vehicle and the installed telematics unit. The vehicle state consists of hardware agnostic data, that is independent of the installed telematics unit. The presence of information depends on which data is provided by the vehicle at a certain time. Therefore, it may differ from vehicle state to vehicle state.

Certain vehicles together with the telematics unit do not provide all data fields, e.g. a scooter will not report a value for the status of doors but a car might. To reflect this reality, there is capability category called 'vehicle state capabilities'. Vehicle state capabilities describe the data fields for which the vehicle can deliver a value. For each property in the hardware agnostic part of the vehicle state, there is a corresponding vehicle state capability. Using GET /vehicles/{vehicle_id} of the Vehicle and Telematics Management API, the list of vehicle state capabilities can be requested.

As a result, the properties present in a vehicle state depend on the vehicle state capabilities of that vehicle. For instance, if the vehicle has the vehicle state capability TOP_CASE_LOCK, the property top_case_lock can be present in the vehicle state. However, it doesn't have to be. If it is not possible to gather information about the top_case_lock at a certain time, the field will be absent from the vehicle state.

Note that vehicle state property names are in snake_case (e.g. top_case_lock), while the vehicle state capabilities are written in UPPER_SNAKE_CASE (e.g. TOP_CASE_LOCK).

Please note that it is possible to receive messages which have an empty vehicle_state: In this case, there has been contact with the vehicle but no additional data has been sent.

Payload
object
metadata
required
object

Carries metadata for a Message along with common fields.

message_id
required
string
ulid

Identifier of this message.

message_type
required
string

The name of the MessageType of this Message.

occurred_at
required
string
date-time

When the message was created according to the producer.

version
required
string

Version of the schema used for validating this message. This may be enriched upon reception by intermediaries. This string uses semantic versioning.

flow_id
string

A flow-id for this message (corresponds to the X-INVERS-Flow-ID HTTP header).

Additional properties are allowed.

data
required
object
vehicle_id
required
string
length <= 12 length >= 5

The unique ID of the vehicle.

received_at
required
string
date-time

UTC timestamp when the state was received.

fleet_id
required
string
length <= 12 length >= 5

The unique ID of the fleet the vehicle belongs to.

triggered_by
object

Describes what triggered the reception of a vehicle state.

channel
required
string

Name of the channel that was used to trigger the reception of a vehicle state.

Specification Extensions:

x-extensible-enum
[
  "BLUETOOTH",
  "API_COMMAND"
]
correlation_id
required
string

If channel is bluetooth this property includes the ID of the bluetooth token that was used to communicate with the vehicle and therefore, triggered the vehicle state. If channel is api_command this property includes the X-INVERS-Flow-ID of the API command that triggered the vehicle state.

Additional properties are allowed.

vehicle_state
required
object

The vehicle state shows the current state of the vehicle and the telematics unit installed in it. At certain times, information about a vehicle state property is not provided by the vehicle and therefore it will not be shown in the vehicle state data. In addition, when a vehicle lacks a certain vehicle state capability, the corresponding property will not be included in the vehicle state data of the vehicle.

altitude_in_meters
object allOf

Altitude of the vehicle.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
number
int32

Altitude in meters.

cellular_signal_quality
object allOf

Indicates how strong the signal of the celluar connection is.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
number
int32 >= 0 <= 5

Value between 0 - 5, where 5 is the highest quality.

center_stand_position
object allOf

Position of the center stand.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
string

Either RETRACTED or EXTENDED.

Specification Extensions:

x-extensible-enum
[
  "RETRACTED",
  "EXTENDED"
]
central_lock
object allOf

State of the central lock.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
string

Can either be LOCKED or UNLOCKED.

Specification Extensions:

x-extensible-enum
[
  "LOCKED",
  "UNLOCKED"
]
doors_status
object allOf

Status of the doors, either OPEN when at least one door is open or CLOSED if all doors are closed.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
string

OPEN when at least one door is open or CLOSED if all doors are closed.

Specification Extensions:

x-extensible-enum
[
  "OPEN",
  "CLOSED"
]
driving_enabled
object allOf

Whether you can start the engine of the vehicle.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
boolean

True means you can start the vehicle. False means you cannot.

fuel_level_in_percent
object allOf

Fuel level of the vehicle in percent (can also be state of charge for electric vehicles).

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
number
int32 >= 0 <= 100

Percentage ranging from 0 to 100.

ignition
object allOf

A vehicle has the vehicle state capability "ignition" only if the vehicle requires the driver to manually disable the ignition. The intended use is for it to indicate whether the disable_driving command should be sent. One might want to check this condition to determine whether a rental can be ended. In particular, one might want to prevent a rental from being ended unless ignition = off.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
string

Either ON or OFF.

Specification Extensions:

x-extensible-enum
[
  "ON",
  "OFF"
]
mileage_in_kilometers
object allOf

How far the vehicle has driven in total. Measured in kilometers.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
number
double >= 0

Measured in kilometers.

position
object allOf

Position of the vehicle.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
object

Position of vehicle (GPS/GLONASS/...).

lat
required
number
double >= -90 <= 90

Latitude of the position.

lon
required
number
double >= -180 <= 180

Longitude of the position.

Additional properties are allowed.

remaining_range_in_kilometers
object allOf

An estimate of how far the vehicle can drive with the remaining fuel or battery charge in kilometers.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
number
double

Measured in kilometers.

top_case_lid
object allOf

State of the top case lid.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
string

Either OPEN or CLOSED.

Specification Extensions:

x-extensible-enum
[
  "OPEN",
  "CLOSED"
]
top_case_lock
object allOf

State of the top case lock.

Additional properties are allowed.

0
timestamp
string
date-time

UTC time of the value as recorded by the vehicle (or the best approximation thereof).

1
value
string

Can either be LOCKED or UNLOCKED.

Specification Extensions:

x-extensible-enum
[
  "LOCKED",
  "UNLOCKED"
]

Additional properties are allowed.

Additional properties are allowed.

Additional properties are allowed.