The Vehicle Messages interface is intended for INVERS customers who need programmatic access to integrate their applications with the INVERS platform.
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.
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.
The messages' payloads are returned as JSON (application/json
).
Date and time values are in UTC in the following ISO 8601
compatible format: 2014-10-17T08:30:00Z
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.
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.
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
).
Production RabbitMQ
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.
Arbitrary value. The full queue name will be given to you during message subscription configuration.
Accepts the following message:
Message with information about the 'VehicleState'
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.
Carries metadata for a Message along with common fields.
Identifier of this message.
The name of the MessageType of this Message.
When the message was created according to the producer.
Version of the schema used for validating this message. This may be enriched upon reception by intermediaries. This string uses semantic versioning.
A flow-id for this message (corresponds to the X-INVERS-Flow-ID HTTP header).
Additional properties are allowed.
The unique ID of the vehicle.
UTC timestamp when the state was received.
The unique ID of the fleet the vehicle belongs to.
Describes what triggered the reception of a vehicle state.
Name of the channel that was used to trigger the reception of a vehicle state.
Specification Extensions:
[ "BLUETOOTH", "API_COMMAND" ]
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.
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 of the vehicle.
Additional properties are allowed.
UTC time of the value as recorded by the vehicle (or the best approximation thereof).
Altitude in meters.
Indicates how strong the signal of the celluar connection is.
Additional properties are allowed.
UTC time of the value as recorded by the vehicle (or the best approximation thereof).
Value between 0 - 5, where 5 is the highest quality.
Position of the center stand.
Additional properties are allowed.
UTC time of the value as recorded by the vehicle (or the best approximation thereof).
Either RETRACTED
or EXTENDED
.
Specification Extensions:
[ "RETRACTED", "EXTENDED" ]
State of the central lock.
Additional properties are allowed.
UTC time of the value as recorded by the vehicle (or the best approximation thereof).
Can either be LOCKED
or UNLOCKED
.
Specification Extensions:
[ "LOCKED", "UNLOCKED" ]
Status of the doors, either OPEN
when at least one door is open or CLOSED
if all doors are closed.
Additional properties are allowed.
UTC time of the value as recorded by the vehicle (or the best approximation thereof).
OPEN
when at least one door is open or CLOSED
if all doors are closed.
Specification Extensions:
[ "OPEN", "CLOSED" ]
Whether you can start the engine of the vehicle.
Additional properties are allowed.
UTC time of the value as recorded by the vehicle (or the best approximation thereof).
True means you can start the vehicle. False means you cannot.
Fuel level of the vehicle in percent (can also be state of charge for electric vehicles).
Additional properties are allowed.
UTC time of the value as recorded by the vehicle (or the best approximation thereof).
Percentage ranging from 0 to 100.
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.
UTC time of the value as recorded by the vehicle (or the best approximation thereof).
Either ON
or OFF
.
Specification Extensions:
[ "ON", "OFF" ]
How far the vehicle has driven in total. Measured in kilometers.
Additional properties are allowed.
UTC time of the value as recorded by the vehicle (or the best approximation thereof).
Measured in kilometers.
Position of the vehicle.
Additional properties are allowed.
UTC time of the value as recorded by the vehicle (or the best approximation thereof).
Position of vehicle (GPS/GLONASS/...).
Latitude of the position.
Longitude of the position.
Additional properties are allowed.
An estimate of how far the vehicle can drive with the remaining fuel or battery charge in kilometers.
Additional properties are allowed.
UTC time of the value as recorded by the vehicle (or the best approximation thereof).
Measured in kilometers.
State of the top case lid.
Additional properties are allowed.
UTC time of the value as recorded by the vehicle (or the best approximation thereof).
Either OPEN
or CLOSED
.
Specification Extensions:
[ "OPEN", "CLOSED" ]
State of the top case lock.
Additional properties are allowed.
UTC time of the value as recorded by the vehicle (or the best approximation thereof).
Can either be LOCKED
or UNLOCKED
.
Specification Extensions:
[ "LOCKED", "UNLOCKED" ]
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.