2. Defining Deliveries

Deliveries are the basic entities of a route, gathering the properties necessary to define conditions for the vehicle routing problem.

The most important property is the location, as was discussed in the last chapter. But in case you need time constraints to be considered (you won't be here otherwise, right?), the time window properties are just as important. And there are others, like e.g. loads.

You can find a a short description of all the properties in our delivery schema in the API reference, for a quick overview of the more important ones take a look at our Basic API Data Structures page.

But let's go slowly. In the most basic case, all you need to create a delivery is a deliverylocation_id. It's one of the ids from the addresses you created in the last chapter.

curl --request POST \
     --url 'https://dispatch.smartlane.io/your_company_name/api//delivery' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: JWT your.Long_Randomfghxlcnebem.Secure_AccessToken' \
     --data '{"deliverylocation_id": 2}'
import requests
from datetime import datetime, timedelta

auth_header = {"Authorization": "JWT your.Long_Randomfghxlcnebem.Secure_AccessToken"}
api_url = "https://dispatch.smartlane.io/your_company_name/api"

url = api_url + "/delivery"

data = {"supplierlocation_id": 2,
        "deliverylocation_id": 3,
        "pdt_to": (datetime.now() + timedelta(days=1)).isoformat(),
        "pdt_from": datetime.now().isoformat()}

response = requests.post(url, headers=auth_header, json=data)

Done, you've defined a delivery and added it to the database. But we at least want to add one more property to our delivery, the time frame within your delivery is planned to arrive at it's destination - the planned delivery time. It's abbreviated to PDT which make up the two parameters pdt_from and pdt_to. So a meaningful delivery could be posted just like above, with the data object looking like this:

{'deliverylocation_id': 2,
 'pdt_from': '2019-04-28T15:00:00.00+02:00',
 'pdt_to':   '2019-04-28T16:00:00.00+02:00'

Now take a look at the response (or don't):

{"id": 1,
 "supplierlocation_id": 1,
 "supplier_address": {"additional": null,
                      "addresstype": "depot",
                      "city": "München",
                      "code": null,
                      "contactcompany": "Company Name",
                      "contactfirstname": "Test",
                      "contactlastname": "User",
                      "country": "Germany",
                      "customernr": null,
                      "default_pdt_from": null,
                      "default_pdt_to": null,
                      "distances": null,
                      "district": null,
                      "email": null,
                      "housenumber": "6",
                      "id": 1,
                      "location": {"coordinates": [11.60772, 48.12469],
                                   "type": "Point"},
                      "phonenr": null,
                      "postalcode": "81671",
                      "street": "Grafinger Straße"},
 "deliverylocation_id": 2,
 "delivery_address": {"additional": null,
                      "addresstype": null,
                      "city": "München",
                      "code": null,
                      "contactcompany": "The Next Door Company",
                      "contactfirstname": null,
                      "contactlastname": null,
                      "country": "DE",
                      "customernr": null,
                      "default_pdt_from": null,
                      "default_pdt_to": null,
                      "distances": null,
                      "district": null,
                      "email": null,
                      "housenumber": "7",
                      "id": 2,
                      "location": {"coordinates": [11.6080874, 48.1251596],
                                   "type": "Point"},
                      "phonenr": null,
                      "postalcode": "81671",
                      "street": "Grafinger Str."},
 "status": 0,
 "load": null,
 "els": 5,
 "pdt_from": "2019-04-28T15:00:00+02:00",
 "pdt_to": "2019-04-28T16:00:00+02:00",
 "tdt_from": null,
 "tdt_to": null,
 "eta_from": null,
 "eta_to": null,
 "ddt_from": null,
 "ddt_to": null,
 "ppt_from": null,
 "ppt_to": null,
 "tfp": null,
 "eta": null,
 "als": null,
 "ata": null,
 "atd": null,
 "return_time": null,
 "custom_id": null,
 "custom_tour": null,
 "code": null,
 "creationtime": null,
 "deliverprio": null,
 "deliveryissuename": null,
 "deliverytype_id": null,
 "distances": null,
 "drivernotes": null,
 "final": null,
 "load_text": null,
 "notes": null,
 "notify_customer_email": false,
 "notify_customer_sms": false,
 "orderindex": 45514,
 "packets": null,
 "pickup_id": null,
 "pickup_ref_id": null,
 "recipientname": null,
 "recipienttype": null,
 "route_id": null,
 "scancode": null,
 "signaturelink": null,
 "tourarea_id": null,
 "vehicle": "car"}

I'm afraid to mention it, but I guess that's confusing. So just go ahead to the next chapter and start planing your first route. You can come back and read about the details once you need to. It's going to make more sense later.

The rest of the chapter is manly dedicated to explaining the delivery's properties as seen above.

Time Attributes

We may group the time attributes of a delivery into three categories.

  1. The times that are used as input for the routing algorithm, which need to be known before planning a tour.
  2. The times that are calculated by the routing algorithm.
  3. The times that are provided by the drivers telematic system. They are used for monitoring and automatic improvement of future predictions.

Inputs - planned times

We already mentioned the the planned delivery time above, the most important attribute that needs to be considered when planning with time windows. Planing with multiple time windows is also possible. They can be set by using arrays of pdt_from and pdt_to, where the nth pair of the two arrays define the nth element, e.g. like

      "pdt_from": ["2020-07-03T10:30:00+00:00",
      "pdt_to": ["2020-07-03T11:30:00+00: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".

There's only one more parameter concerning time, necessary for the planing processing, i.e. as an input parameter - the estimated length of stay. It's abbreviated to els and defines how much time a delivery job is supposed to take (in minutes).


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, unless you're in UTC±0.

Time spans are often specified in minutes for convenience.

But you may have already noticed that there's 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 between the planned delivery time span (it doesn't just in case the route cannot satisfy the time constraints).

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 (compare chapter 4).

The second maybe even more important purpose of the eta is, that it gets updated in real time based on the current traffic conditions and the drivers position. This means it is also dependent on the third group, the actual times.
If everything out on the street works as expected, it it always between tdt_from and tdt_to. But of course it doesn't always work as expected.

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.

Telematics data - actual times

So after to the first group the planed times (pdt and els) and the second group of calculated times (tdt, eta and ddt), here is the third group: The times that state when it actually happed. These times are communicated to our system, e.g. from a third-party telematics device via Smartlane's tracking API and are necessary to to monitor the drivers actions. But most importantly, it is the data, our algorithm learns from and allows our AI to plan better with each delivery (more about this in chapter 4.

These are not time-frames but rather time-stamps. The actual time of arrival atais set when the drivers position is close to the target delivery.
The actual time of delivery is set when the driver actually pushes a button, e.g. marking the delivery as done.
The actual length of stay als is the real world counterpart of the estimated length of stay els.

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.

So finally, here's an overview of the times in tabular form





planned delivery time

Manual input based on customer wishes.


target delivery time

Calculated possible time span of delivery, based on pre-defined time constraints and traffic forecasts.


driver delivery time

Time span of delivery to be communicated to the driver based on TDT.


estimated time of arrival

Time span of delivery to be communicated to the end customer based on TDT.
Used for customer notification.


actual time of arrival

Time of the driver's actual arrival at the customer's address (via driver's GPS position)


actual time of delivery

Time of the driver's actual succesful delivery at the customer's address (timestamp of POST /deliverydone/{delivery_id})


planned pickup time

Manual input based on customer wishes.


estimated length of stay (minutes)


actual length of stay (minutes)


driving time from preceding delivery