Vehicle Management API⚓︎
The Vehicle Management API allows you to manage all the vehicles and telematics units of your fleet.
Vehicles⚓︎
As the name implies, the Vehicle Management API is centered around vehicles. Vehicles are addressed and identified by their vehicle_id, which is generated when a vehicle is added to your INVERS OneAPI fleet. The Vehicle Management API provides endpoints to view all vehicles of your fleet in a paged list, but also endpoints to retrieve detailed information about a particular vehicle, such as master data, installed telematics unit, or the latest vehicle state. Furthermore, there is an endpoint to alter the master data of a vehicle, such as VIN, custom name, or license plate.
In the following sections, important parts of the vehicle as it is defined in the Vehicle Management API will be explained in more detail. We recommend you carefully read those sections to understand the basic concepts around vehicles and their assigned telematics units within the INVERS OneAPI.
Master data⚓︎
The master data of a vehicle contains its basic information, such as VIN, license plate, or transmission. If you would like to know exactly which master data can be stored for each vehicle, have a look at the API specification in the box in the top right, or the example below.
Example
This example shows how the master data of a vehicle can look like.
"master_data": {
"vin": "R1NBDNB16J1000135",
"license_plate": "RKL-832",
"brand": "Audi",
"model": "A3",
"custom_name": "MyAudiA3",
"fuel_type": "ELECTRIC",
"year_of_production": "2019",
"transmission": "AUTOMATIC",
"vehicle_type": "CAR"
}
You can enter and change all vehicle master data as you wish, either by using FleetControl or the Vehicle Management API. Changing a vehicle’s master data has no effect on the vehicle’s connectivity. This data is solely intended for you to identify and filter the vehicles of your fleet.
Custom fields⚓︎
Example
"custom_fields": {
"seats": "5",
"color": "black"
}
Use custom fields to add additional information to your vehicles. A custom field essentially is a key/value pair. You can define both, keys and values, freely.
Keys and values are both handled as strings within the Vehicle Management API. Once added to your vehicles, you can use custom fields to filter them within FleetControl or within your own applications.
Tags⚓︎
Example
"tags": [
"in_maintenance",
"demo_night"
]
With tags, you can mark vehicles of a fleet and consequently group them by one or multiple tags. This makes them easier to find, e.g. within FleetControl.
You can use any character within tags, a tag can however not be empty or consist exclusively of blanks / whitespace characters.
Life status⚓︎
Each vehicle of your fleet has a life status. The life status is automatically determined by the INVERS OneAPI and provides information about the current connection status of the vehicle. As all vehicles report their status in predefined cycles instead of keeping a permanent cellular connection, the life status is based on the events reported by the vehicle. The status can have four values:
ONLINE- The vehicle has sent any data within the last 35 minutes. It can be assumed that the vehicle is connected and working.
OFFLINE- The vehicle has not sent an event for more than 35 minutes. This does not automatically imply that the vehicle or the installed telematics unit has a problem, but might be a first indicator for connectivity problems. The vehicle might not properly handle vehicle commands, but you can try to send them.
DISAPPEARED- The vehicle cannot be used, as it has disappeared from the API or cloud services of a third-party telematics manufacturer. This applies to vehicles added using OEM Integrations only.
ABSENT- The vehicle was in status
OFFLINEfor a long time period (>7 days). It is very likely not ready to handle vehicle commands. SETUP- The vehicle is currently in the telematics unit setup process, it is not yet ready for use. This is the initial value after a vehicle has been added to your fleet via the Vehicle Lifecylce API. The life status is automatically updated to either
ONLINEorOFFLINEonce the setup process is completed and the vehicle has contacted the INVERS OneAPI. Depending on the type of telematics unit built into the vehicle, the duration of the setup process usually ranges from several seconds to a couple of minutes.
Operation status⚓︎
The operation status is designed to help you group your vehicles based on their current operational status within your fleet. Therefore, unlike the life status, you can set the operation status manually via the Vehicle Management API with PATCH /vehicles/{vehicle_id}/operation-status.
The operation status can be set to one of the following values:
OPERATING- The vehicle is operating and can be actively used by your customers. A vehicle has this status by default.
MAINTENANCE,GARAGE,DEFECT,FRAUD,DECOMMISSIONED- These five states can be used to denote vehicles of your fleet that are currently under maintenance, permanently broken, have been stolen, or are simply not ready to be used yet. Assigning either one of these states to vehicles has no effect on the usability of those vehicles, i.e. you can still send vehicle commands to any of them. These states simply exist to help you manage the vehicles of your fleet effectively. For example, you can use the states as filter criteria within FleetControl or handle and create different alarms based on the operation status currently set for the vehicle.
Rental status⚓︎
The rental status can be used to mark vehicles as IN_RENTAL or NOT_IN_RENTAL. You would typically change the rental status each time control of a vehicle is transferred to or from a customer (at rental start and rental end).
Mainly, the rental status is used by the INVERS OneAPI to conform to data protection packages that are configured for your fleet.
While a vehicle is IN_RENTAL certain data points, like the vehicle’s position, may be excluded from vehicle states.
Also, the request-vehicle-state command may be blocked while the vehicle is IN_RENTAL.
Both of these effects depend on the enabled data protection packages of your fleet.
Further, certain requests like firmware updates are blocked, in order to not disrupt the rental of the customer.
The rental status can also be used as a filter criteria within FleetControl.
If you are using the Trips feature, it can be very useful to set the rental status and use it as a trip trigger. This way, you can ensure that trips and trip metrics are precisely matching the actual trip or rental of your customers. Please refer to our trips documentation for additional information.
Setting the rental status is done via the Vehicle Management API, see PUT /vehicles/{vehicle_id}/rental-status.
This API endpoint returns the entire vehicle, including the latest vehicle state, so you can easily integrate the request into your rental flow.
You may also utilize the request_new_vehicle_state query parameter to request the most recent vehicle state from the vehicle, saving you an additional request, depending on your rental flow implementation.
Note that requesting a new vehicle state can result in a longer request duration or even fail, if the vehicle has bad signal quality or is offline.
Capabilities⚓︎
Vehicles can execute commands and provide data in the form of vehicle states (see below). However, no vehicle supports all commands. For example, a car will not be able to execute a command such as unlocking its top case. That is why vehicles have capabilities. In order to find out more about capabilities, go to vehicle capabilities.
Command capabilities and vehicle state capabilities are assigned to a vehicle when it is added to your fleet or, more precisely, when a telematics unit is added to the vehicle. When retrieving a vehicle via the Vehicle Management API, both types of capabilities will be present in the response and you can use this information for your rental workflows and other processes you might create on top of the INVERS OneAPI.
Latest vehicle state⚓︎
A vehicle state provides information about the current state of the vehicle and the installed telematics unit. It always consists of hardware-agnostic data, which is independent of the installed telematics unit. All vehicle state values within this part have been normalized/generalized by the INVERS OneAPI, which is one of the key advantages of connecting your vehicles through this API.
Some telematics brands offer additional data that can hardly be generalized to a hardware-agnostic value or where a lot of the value would be lost in generalizing it. If this is the case, those data points will be present in the vehicle state within a separate section, which is then specific to the telematics brand.
Each time a vehicle reports new data in the form of a new vehicle state, it does not necessarily report all data points. There are two reasons for this:
- Not all vehicle state values can be reported by all vehicle types or telematics brands (see vehicle state capabilities)
- A telematics unit does not always report all values, e.g. some values are updated and transmitted more frequently than others
In order to compensate for the latter, the Vehicle Management API offers a latest_vehicle_state for each vehicle. It always contains all the vehicle state values the vehicle can report, and for each individual value the most recent one that was received.
Telematics unit⚓︎
The Vehicle Management API also tells you which telematics unit is installed and configured in your vehicle. You can see basic information about the telematics unit, such as the manufacturer, brand, and model. In addition, the telematics_unit_id is part of the telematics_unit property within your vehicle. This ID is assigned by the telematics manufacturer and as such only unique in combination with the brand of the telematics unit.
For example, the QNR of a CloudBoxx is only unique within the telematics brand “CloudBoxx”. For the unique identification of a telematics unit outside of a vehicle, where the vehicle_id serves as the unique identifier, the corresponding telematics brand is always required.
The telematics_unit_id is equivalent to the identifier assigned by the manufacturer.
Example
These are examples for the identifiers that are used as the telematics_unit_id for different brands:
- CloudBoxx: QNR
- INVERS OBD Dongle: IMEI
- NIU: Device Serial Number
- OKAI: IMEI
- Segway: IMEI
- Simulated: ULID
- Car OEMs: VIN
Example⚓︎
The following example shows how to get a list of vehicles in your fleet. First, follow instructions to get an access token in order to retrieve a valid access token for the INVERS OneAPI.
curl -X GET \
https://api.invers.com/vehicles \
-H 'Authorization: Bearer ❰access_token❱' \ # (1)!
-H 'Content-Type: application/json'
- Don’t forget to fill in your access token.
This route offers cursor-based pagination. If needed, use the limit parameter to limit the length of the resulting list. In order to navigate through the results, use the cursors provided in the result object in subsequent calls and omit the limit. If the request has been successful, a JSON object is returned along with HTTP status code 200.
Depending on the vehicle and the telematics unit installed the extent of information may vary. Here is an example of what the response might look like:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 | |