-> Defining shipments

Our service optimizes the routes by assigning shipments (deliveries or pickups) to vehicles considering constraints like territory, time window, capacity and special attributes. Shipments hold the information required to plan the routes:

1. Location
2. Time windows
3. Shipment type - delivery or pickup
4. Load dimensions like pallet places, weight & height, volume, loading meter
5. Required attributes of a vehicle like trailer, liftgate or ADR

You can find a short description of all the properties in our delivery schema in the API reference.

The shipment_type sets the type of a shipment as delivery or pickup. We also support Directs - freight that is picked up on tour and delivered on tour, so there is no depot loading or unloading. Deliveries that have such a pickup on tour reference those using the pickup_ref_id.

Expected length of stay (els)

We consider the expected length of a stay for loading and unloading shipments.
It is composed of two values:

1. The fixed_els: The fixed part of the loading and unloading time for a shipment.
2. The variable_els: The variable part of loading and unloading time based on the shipment loads.

The total els for a shipment will be calculated as fixed_els + n * variable_els, where n is the amount of the corresponding load parameter.

Note: The variable_els can just be defined for one load parameter of a shipment.

We follow a hierarchy of els settings in order to fetch the best value possible:

1. fixed and variable els defined in shipment data
2. fixed and variable els defined on a vehicle level
3. fixed and variable els defined on a vehicle type level
4. Fallback to default fixed and variable els stored in our DB if no els is provided in an upper level

Time Attributes

We can group the time attributes of a delivery into two categories.

1. The times that are used as input for the routing algorithm, which need to be known before planning a tour, e.g. the pdt_from, pdt_to and els settings.
2. The times that are calculated by the routing algorithm. These are e.g. the "target delivery time - tdt" or the "expected time of arrival - ETA".

Inputs - planned times

We can also plan with multiple time windows. They can be set by using arrays of pdt_from and pdt_to:

      "pdt_from": ["2020-07-03T10:30:00+02:00",
		          "2020-07-03T12:30:00+02:00"],
      "pdt_to": ["2020-07-03T11:30:00+02:00",
		      "2020-07-03T13:30:00+02:00"]

So in this example we have two time windows: The first from "10:30" to "11:30", the second from "12:30" to "13:30".

📘

ISO Time

Make sure that all dates and times are formatted according to the ISO 8601 standard.
Be aware that the time zone designator is mandatory.

Time spans are often specified in minutes for convenience.

But you may have already noticed that there are many more properties, having _from and _to in their names, and all of them describe time spans, calculated by our algorithm. So let's explain them one by one.

Outputs - calculated times

The first is the target delivery time, abbreviated to tdt_from and tdt_to. It defines the time span, that when met by the driver, allows that the next delivery tdt can also be met. This time span is always within the planned delivery time span.

The next time span estimated time of arrival eta is derived from the target delivery time tdt. It serves some important functionality. First of all, the tdts can be very wide when the planned delivery time windows (pdts) are very large. So it narrows them down to a more definite interval. This is also the time that is communicated to the end customer.

The last of this bunch of time spans is the driver delivery time ddt. It is the time span, that is supposed to be communicated to the driver to tell him at what time it would be best to arrive. It is very similar to the eta, but usually a little earlier.

One more time is missing: the planned pickup time ppt. We fully support pickup and delivery services, but at this point is beyond the scope of this tutorial.

A time related settings overview: