Use Case
This API is used to provide updates for a transport from the implementer's inhouse system, usually a TMS. It is possible to send updates for various aspects of the transport:
GPS positions and temperature data from the sensors.
Delivery Events (Arrival to, departure from,...)
Delivery loading/unloading statuses (ETA, remaining distance)
License plate of the truck carrying the order out (To let stakeholders know about it)
Note that the payloads sent are cumulative for data which is timestamped, like events or GPS positions. This means that each new payload will add on top of the previous payload, but will not replace it. Previously sent data does not need to be re-sent with each new update. For deleting a previously sent event there is a special deleted_at flag available, which should be used together with correct event_id.
Endpoint
POST https://api.transporeon.com/rtv/v1/transports/status
Identifiers used in the payload
The API allows the user to specify transport or delivery based identifier. The transport_id and transport_number refer to the identifiers provided by Transporeon or the shipper respectively. Alternative is to use the delivery based identifier delivery_id or delivery_number.
Generally, a transport specific update applies to all deliveries within that transport. So for most cases a transport specific update is enough.
Sending Transport GPS Positioning Data
The transport_updates array in the payload allows to send multiple updates at once for the same transport with different timestamps or for different transports.
{
"transport_updates": [
{
"transport_id": "983549358",
"vehicle_telemetry": {
"timestamp": "2019-08-24T14:15:22Z",
"position": {
"lat": 59.4365094,
"lng": 24.7428656
},
"direction": 132.6,
"speed": 75,
"odometer": 523145,
"is_engine_running": false,
"front_axle_weight_kg": 0,
"rear_axle_weight_kg": 0,
"total_weight_kg": 0,
"altitude_meters": 143,
"fuel_level_pct": 20.4,
"clean_source_pct": 20.4,
"total_fuel_consumption_liters": 4004.11
}
},
{
"transport_id": "12345678",
"vehicle_telemetry": {
"timestamp": "2019-08-24T15:12:22Z",
"position": {
"lat": 57.4365094,
"lng": 23.7428656
},
"direction": 132.6,
"speed": 75
}
}
]
}
Note that once the transport has received a GPS data, it's considered permanent and the next GPS datapoint must have a timestamp newer than the previous one to avoid it being discarded. Therefor the GPS tracking timestamps must always be monotonically increasing within the context of one transport/delivery, it's not possible to backfill older points in history after there has been a newer GPS position.
Sending Transport Loading/Unloading Statuses and Events
Transport events can be sent to indicate any event, for example a loading or unloading has taken place or the vehicle has reached the station for loading/unloading.
Transport events are limited by timestamp to be a maximum of one year in the past and 30 minutes in the future.
For a Transport
{
"transport_updates": [
{
"transport_number": "1234567",
"loading_status": {
"timestamp": "2019-08-24T14:15:22Z",
"eta": "2019-08-24T15:15:22Z",
"events": [
{
"event_id": "1a2b3c",
"timestamp": "2019-08-23T15:15:22Z",
"qualifier": "heading_towards",
"position": {
"lat": 59.4365094,
"lng": 24.7428656
}
}
]
}
}
]
}
For Multiple Deliveries
{
"transport_updates": [
{
"delivery_id": "123456",
"loading_status": {
"timestamp": "2019-08-24T15:00:00.00Z",
"eta": "2019-08-24T14:15:22Z",
"estimated_remaining_distance_meters": 5000.151,
"events": [
{
"event_id": "6f6f6f",
"timestamp": "2019-08-24T15:00:00.00Z",
"qualifier": "started",
"position": {
"lat": 59.4365094,
"lng": 24.7428656
}
}
]
}
},
{
"delivery_id": "123457",
"loading_status": {
"timestamp": "2019-08-24T15:00:00.00Z",
"eta": "2019-08-24T14:15:22Z",
"estimated_remaining_distance_meters": 5000.151,
"events": [
{
"event_id": "1a2b3c",
"timestamp": "2019-08-24T15:00:00.00Z",
"qualifier": "started",
"position": {
"lat": 59.4365094,
"lng": 24.7428656
}
}
]
}
}
]
}
Sending a Custom Qualifier
Custom qualifier can be sent for an event in case the predefined qualifiers don't match the specific event nature. Custom qualifiers do not trigger any specific action within the status calculation system, but the event will be visible on examination of the transport.
{
"transport_updates": [
{
"transport_number": "1234567",
"unloading_status": {
"timestamp": "2019-08-24T14:15:22Z",
"eta": "2019-08-24T15:15:22Z",
"events": [
{
"event_id": "1a2b3c",
"timestamp": "2019-08-23T15:15:22Z",
"qualifier_custom": "Waiting for unloading / Idle",
"position": {
"lat": 59.4365094,
"lng": 24.7428656
}
}
]
}
}
]
}
Sending Temperature Data
Temperature data can be sent similarly to GPS data in larger batches. Similarly to GPS data, the timestamps in temperatures are expected to be monotonically increasing within the reefer context. If a temperature is sent for a reefer which has already received a later value, then the temperature with older timestamp is not processed and is discarded.
{
"transport_updates": [
{
"transport_number": "1234567",
"temperatures": [
{
"timestamp": "2018-01-01T01:00:00Z",
"reefer_id": "default",
"sensor_readings": [
{
"compartment_id": "default",
"sensor_id": "main",
"temperature": -1.015
},
{
"compartment_id": "default",
"sensor_id": "back",
"temperature": -0.1
}
]
},
{
"timestamp": "2018-01-01T00:00:00Z",
"reefer_id": "default",
"sensor_readings": [
{
"compartment_id": "default",
"sensor_id": "main",
"temperature": -0.9
},
{
"compartment_id": "default",
"sensor_id": "back",
"temperature": -0.1
}
]
}
]
}
]
}
The structure of the data looks as follows:
---------------------------------------- ---------------------------------------- | reefer 1 | | reefer N | | --compartment1- --compartmentN- | | --compartment1- --compartmentN- | | | sensor 1 | | sensor 1 | | | | sensor 1 | | sensor 1 | | | | | | | | | | | | | | | | sensor 2 | | sensor 2 | | | | sensor 2 | | sensor 2 | | | | | | | | | | | | | | | | senor n | | senor n | | | | senor n | | senor n | | | --------------- --------------- | | --------------- --------------- | | | | | ----------------------------------------|===|----------------------------------------
There can be one to many reefers.
Each reefer can serve one to many compartments.
Each compartment can have one or more sensors
Completing a Transport
In case the transport does not complete automatically due to lack of signal or unloading events, it is possible to complete the transport by using completed event qualifier.
{
"transport_updates": [
{
"transport_number": "1234567",
"transport_events": [
{
"event_id": "123cf31a",
"timestamp": "2018-01-01T00:00:00Z",
"qualifier": "completed",
"position": {
"lat": 51.5074,
"lng": 0.1278
}
}
]
}
]
}
Deleting an Existing Event
In some cases you might want to delete a previously sent event. The API allows it by redefining the event with the deleted_at property being set at current time.
{
"transport_updates": [
{
"transport_number": "1234567",
"loading_status": {
"events": [
{
"event_id": "1a2b3c",
"timestamp": "2019-08-23T15:15:22Z",
"deleted_at": "2019-08-23T18:15:22Z"
}
]
}
}
]
}