FAQ on Visibility APIs

Can I set my own rules for when the tracking should start?

Before considering to implement this feature, be aware that it should only be used in special cases. Always consult our support team.

It is not recommended to override the tracking start time, unless modifying the visibility window is really necessary. Usually the automatic detection of tracking start works well, so explicitly setting the start_tracking_at should be avoided whenever possible.

Overriding the default tracking start time can be used if the specific time when truck starts to drive towards a loading or unloading stop is known.

It allows to

• extend the time when visibility is provided for loading and

• limit time when visibility is given for unloading.

The Visibility API allows to specify a specific point in time when to start tracking the vehicle by adding start_tracking_at field to the vehicle in the allocation message.

This will override the default tracking start time that is based on distance to the stop, timeslot, leaving previous stop and other conditions.

By default, the truck is tracked for unloading immediately after loading, so setting tracking start time allows to

• "hide" trucks if they are doing other jobs after departing from loading,

• there are intermediate depots, transport modes (trains, ferrys etc) before starting with last mile delivery.

The "tracking start" setting activates both ETA and truck location visibility (i.e. snail trail on map) at the given time.

Example for an allocation message with explicitly setting the start_tracking_at parameter:

What's the difference between providing visibility vehicle- or transport-based?

There are different ways how data providers (i.e. carriers) can provide visibility for transports:

1. Connect your vehicles directly using your telematics (GPS) provider

2. Connect your subcarriers and ask them to connect their vehicles.

3. Send data from your inhouse system, in case you don't have your own vehicles or have visibility data consolidated in your inhouse system.

(1) and (2) are for vehicle based visibility.

• Transporeon receives vehicles that need to be allocated to a transport so that the tracking is initiated

(3) is for transport based visibility.

• The carrier directly sends data on a transport using a transport identifier.

• There is no allocation in the "classical sense" that should be done (allocation via the Visibility Hub interface or using the /transport/{identifier_type}/{identifier_value}/allocation endpoint) as our system would only consider vehicle based visibility data if there has been an allocation. The license plate can still be optionally added to the tour (using the /transport/status endpoint).

Open

Read more about that topic here.

What's the reason behind receiving a 409 Conflict http error?

In case you are attempting to interact with a transport based on an identifier that originates from the creator of the transport (usually the customer), the uniqueness can't be guaranteed.

These customer defined identifiers are:

• transport_number

• delivery_number

• order_number

• purchase_order_number

In case you receive this error when using one of the identifiers above, we recommend doing a lookup for the corresponding Transporeon generated identifiers, where uniqueness is guaranteed:

• transport_id

• delivery_id

See here for more information on which identifiers are available in the API.

How can I interpret the cancellation_reason as part of the transport status endpoint and Webhook API?

The label of the cancellation_reason field provides more details about why a certain transport didn't finish tracking.

Have a look at the “Tracking cancelled reasons” help center article here to learn more about the respective cancellation reason.

Given the technical qualifier as part of the API response, you can use the table below to figure out the actual cancellation reason label (used in the Visibility Hub application).

Questions to the scenario: Multiple vehicles are allocated to a transport

What happens to the first vehicle if the automatic switch to the next vehicle is not detected?

Visibility Hub will keep on tracking the first vehicle up until

1. The auto_switch is detected OR

2. The start_tracking_at time is reached (which acts as a fallback, see below) OR

3. The tracking is completed (e.g. all stops are visited) OR

4. The tracking is cancelled (e.g. because not all stops could be visited or something else during tracking went wrong).

How does the start_tracking_at parameter work in case allocation_switch_type = auto_switch?

When multiple vehicles are involved in a transport (see here) and the switch_type is defined as auto_switch, start_tracking_at defines the latest time when the switch to the next vehicle happens. Means: If a switch is detected before that time, it's executed earlier.

What happens if a regular “real-time” allocation is done after vehicles were allocated with allocation_switch_type = auto_switch?

Example of allocations on one transport:

• Vehicle A (regular)

• Vehicle B (auto_switch)

• Vehicle C (regular)

If the switch to Vehicle B already happened, then the alloation of Vehicle C leads to an immediate switch from Vehicle B to Vehicle C.

If the switch to Vehicle B didn’t happen already, then the allocation of Vehicle C leads to a switch from Vehicle A to Vehicle C (and Vehicle B is skipped).

What is the API rate limit?

VH public-api uses ratelimits for all endpoints. The limit is 25 requests per second (per user) with a bit of headroom for burst requests.

Each response has the following HTTP headers connected to the rate limit:

• X-RateLimit-Limit

  • Shows the overall number of available requests per time period

• X-RateLimit-Remaining

  • Shows how many requests are remaining in current time period

• X-RateLimit-Reset

  • Date in RFC 7231 format showing when the rate limit resets

In case the rate limit is reached, HTTP 429 error code is returned

In addition to the headers above, the following headers are also returned in case of error:

• Retry-After

  • Time in seconds to wait until the limit resets and request could be tried again

Examples:

• HTTP 200:

  X-Ratelimit-Limit: 25 X-Ratelimit-Remaining: 8 X-Ratelimit-Reset: Tue, 09 Jul 2024 07:00:24 GMT

• HTTP 429:

  X-Ratelimit-Limit: 25 X-Ratelimit-Remaining: 0 X-Ratelimit-Reset: Tue, 09 Jul 2024 07:00:24 GMT Retry-After: 1

Implementors should handle rate limit errors (HTTP 429 error codes), while keeping in mind that the actual limits may change without prior notice.