Fetch Visibility Data into your Inhouse System

Owned by ser_hcskb_api
Last updated: Jul 03, 2024 by Faruk Mercan
21 min read

The following endpoints allow to get visibility data for currently tracked or recently completed transports.

State Definition of a Working or Finished Transport

A transport is defined as working, when Transporeon system started to calculate an ETA for the first stop. This is dependent on several factors, such as time, distance, signal quality, transport length, timeslots, etc.

A transport is defined as finished, if system ended to track this transport: Either all stops were visited and the tracking was concluded or it failed for different reasons (see cancellation_reason for details).

Lookup of One Specific Transport

You can get visibility data for one specific transport by querying the respective RESTful resource by defining the transport_number or transport_id (see General chapter for more information on those fields).

To get visibilty for one specific transport, you must provide the following URL parameters:

  • The identifier_type that should be used to uniquely identify the transport. The available types are:

    • transport_id

    • transport_number

  • The identifier_value: The actual value of the identifier.

Make an authenticated GET request as shown in the example below:

https://api.transporeon.com/rtv/v1/transports/{identifier_type}/{identifier_value}/status

The response contains general infos about the transport (identifiers, location, etc.) as well as the visibility relevant fields and objects, especially:

  • transport_sharing_url: Non-authenticated (public) link of the transport visibility.

  • delivery_sharing_url: Non-authenticated (public) link of the delivery. This view is also known as "Customer Portal".

  • vehicle_telemetry: Latest known position/speed/heading of the vehicle (if available)

  • vehicle_data: Metadata of the vehicle, foremost the license_plate_number

  • state: The tracking state of the transport. See below for more details.

  • rtv_info: Status (see section below), ETA (incl. source), ATA (incl. status), remaining distance (if available), visibility (if available)

    • visibility : Visibility information of the transport including visibility_index and main_visibility_issue. Only available under top level rtv_info when the transport is in the finished state. See here for more details about visibility_index

  • cancellation_reason: The reason why the tracking of a transport was cancelled. See FAQs for more details.

  • temperatures: If available. See here for details

 

{ "transport_id": "782489934", "transport_number": "117547", "state": "is_working", "tracking_start_time": "2022-12-19T11:00:00.000Z", "transport_sharing_url": "https://app.sixfold.com/go/b71fb6c0ccbcabdd1113c1fab106f2e8982273a73a9fae5a5ae3c426ab1a666e", "vehicle_telemetry": { "timestamp": "2022-12-19T16:11:55.030Z", "position": { "lat": 48.87721, "lng": 10.16599 }, "speed": 24.615384615384617, "heading": 341.7972066517246 }, "vehicle_data": { "license_plate_number": "UL-RTV 24189" }, "deliveries": [ { "delivery_id": "377843916", "delivery_number": "62305", "loading": { "location": { "location_id": "233576000", "gate_id": "233576276", "gate": "Outbound Visibility Hub", "name": "Berlin Beverages Loading", "booking_location_name": "Ulm", "address": { "full_address": "Magirus-Deutz-Str. 16, 89077, Ulm, DE", "street_address": "Magirus-Deutz-Str. 16", "city": "Ulm", "country": "DE", "zipcode": "89077" }, "position": { "lat": 48.398875, "lng": 9.959085 } }, "rtv_info": { "status": "departed", "ata": "2022-12-19T15:15:49.830Z", "atd": "2022-12-19T15:24:01.121Z", "ata_status": "delayed", "delay_duration": "P0Y0M0DT0H50M49S" }, "timeslot": { "begin": "2022-12-19T14:30:00.000Z", "end": "2022-12-19T14:45:00.000Z" }, "sequence_number": 0 }, "unloading": { "location": { "name": "Konsta Group", "address": { "full_address": "Saarländerstr. 2, 4179, Leipzig, DE", "street_address": "Saarländerstr. 2", "city": "Leipzig", "country": "DE", "zipcode": "4179" }, "position": { "lat": 51.327701595, "lng": 12.310079644 } }, "rtv_info": { "status": "en_route", "eta_checked_at": "2022-12-19T16:12:59.761Z", "eta": "2022-12-19T22:23:10.530Z", "estimated_remaining_distance": 383730, "eta_status": "delayed", "eta_source": "internal" }, "timeslot": { "begin": "2022-12-19T19:00:00.000Z", "end": "2022-12-19T20:00:00.000Z" }, "sequence_number": 1 }, "delivery_sharing_url": "https://app.sixfold.com/go/2ab6a18901f1813b2f7a3deee3db89153133e491754e8fbb462a05a0799980d5" } ], "temperatures": [ { "timestamp": "2023-02-19T16:17:45.000Z", "reefer_id": "default", "sensor_readings": [ { "sensor_id": "main", "compartment_id": "default", "temperature": -21 } ] } ] }

Search and Filter All Transports

With the following request, you can search and filter for currently tracked and completed transports.

You need to use one of the following search (query) parameters:

  • transport_number

  • transport_id

  • transport_filter: Transports with matching transport_number or transport_id or delivery_number or purchase_order_number or order_number will be returned. The transport_filter parameter supports partial search. This is especially helpful if the exact field used by the customer is not known / varies from customer to customer or if multiple transports/deliveries should be returned that match the same criteria.

Make an authenticated GET request as shown in the example below:

https://api.transporeon.com/rtv/v1/transports/status?transport_filter=6230

Response (for readability reasons, the payload was shortened to the most crucial parts):

{ "transports": [         { "transport_id": "782489931", "transport_number": "117544", "state": { "label": "tracked", "is_working": true, "is_finished": false, }, "tracking_start_time": "2022-12-19T09:00:00.000Z", "transport_sharing_url": "https://app.sixfold.com/go/662ff693058806f581d8d015fc6f6b90bd2c507129197d1e2e040453abd640d3", "vehicle_data": { "license_plate_number": "UL-RTV 24186" }, "deliveries": [ { "delivery_id": "377843913", "delivery_number": "62302", "loading": { "location": {...}, "rtv_info": { "status": "departed", "ata": "2022-12-19T13:14:24.531Z", "atd": "2022-12-19T13:22:36.531Z" }, "timeslot": {...}, "sequence_number": 0 }, "unloading": { "location": {...}, "rtv_info": { "status": "arrived", "ata": "2022-12-19T15:01:35.547Z", "ata_status": "delayed", "delay_duration": "P0Y0M0DT0H36M35S" }, "timeslot": {...}, "sequence_number": 1 }, "delivery_sharing_url": "https://app.sixfold.com/go/79c76706f8a641b4b6bfd2e6e726de38c108234ef76c541b55f1a6b09f2e74b7" } ], "temperatures": [...] } ] }, { "transport_id": "782489929", "transport_number": "117543", "state": { "label": "tracked", "is_working": true, "is_finished": false, }, "tracking_start_time": "2022-12-19T11:00:00.000Z", "transport_sharing_url": "https://app.sixfold.com/go/27ed64aa3a4e1bfebb29c5cf700ad356edac20f4aced756d68c3192221b837aa", "vehicle_data": { "license_plate_number": "UL-RTV 24185" }, "deliveries": [ { "delivery_id": "377843911", "delivery_number": "62301", "loading": { "location": {...}, "rtv_info": { "status": "departed", "ata": "2022-12-19T12:58:10.379Z", "atd": "2022-12-19T13:06:13.379Z" }, "timeslot": {...}, "sequence_number": 0 }, "unloading": { "location": {...}, "rtv_info": { "status": "arrived", "ata": "2022-12-19T16:12:55.810Z", "ata_status": "delayed", "delay_duration": "P0Y0M0DT0H17M55S" }, "timeslot": { "begin": "2022-12-19T15:00:00.000Z", "end": "2022-12-19T16:00:00.000Z" }, "sequence_number": 1 }, "delivery_sharing_url": "https://app.sixfold.com/go/ed1a7c33fbc10c67ee38127aae6c29c75054a612903473fbf0dfc532d74a2365" } ], "temperatures": [...] } ], "page_info": {} }

 

→ Two transports were returned, as the search string "6230" was found in two delivery_numbers:

  • "delivery_number": "62302"

  • "delivery_number": "62301"

Object Details rtv_info & state

Real-time visibility information is always recalculated from the latest known data provided to Transporeon. The rtv_info object involves predicted ETA (estimated time of arrival) or ATA/ATD (actual time of arrival/departure), depending on the status.

RTV info of a loading, waypoint or unloading stop can be in one of those statuses from the perspective of the tranport execution:

  • unvisited - no stop visit detected, e.g. when the truck hasn't arrived yet

  • en_route - truck is driving towards stop. The stop is the one in the tour with the smallest ETA.

  • arrived - truck has arrived to the stop

  • departed - truck departed from the stop

Depending on the status (object on delivery loading/waypoint/unloading level), either ETA or ATA/ATD information per stop is shown.

  • For unvisited and en_route stops, ETA is shown, if it's possible to calculate it.

  • For arrived and departed stops, actual time of arrival/departure (ATA, ATD) is shown.

The state (object on transport level) describes the overall state of the transport:

  • label - human readable label of the tracking state. Can be any string and the values returned are a subject to change.
    Examples: tracked, cancelled

  • is_working - the transport is currently being tracked.

  • is_finished - the tracking for the transport is completed OR the tracking for the transport failed or was cancelled. For details on the cancellation_reason, see the FAQ page .

Temperature Data

In the following, specific information in regards to temperature data for refrigerated transports is given.

How can the temperature data be interpreted?

In case there is temperature data available for the transport, a certain set of temperature related data fields will be included.

The structure of the data looks as follows:

Scheme of a truck structure: ---------------------------------------- ---------------------------------------- | 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 to many sensors

  • Sensors may not be tied to a compartment (see that section to implement it)

In practice, it highly depends on the data source on how many of which entities are available.

There are two types of sensors:

  1. Sensors that are part of the reefer and represent a setting thereof. These sensors can be tied to a compartment. The sensor_id represents a specific type of sensor: SupplyAirTemp, ReturnAirTemp, Setpoint.

  2. Sensors that measure the temperature. These sensors can not be tied to a compartment. The sensor_id represents a simple name, like temp1.

Compartments have the following naming convention:

If the sensor_reading can't be related to a compartment:

Example of payload:

How do I know which delivery is in which compartment?

With the currently available data, it's not possible to know that: There is no connection between delivery and compartment, as this data is not available to Visibility Hub.

 

Transporeon status page I Privacy Policy I Imprint