As it might be a bit too much, to get an overview of the whole API reference in one glance, this page probably is a bit too dense as well. But hopefully it can help to put some stuff of this stuff into context. It's intended to be a short summary of the main data structures, you'll encounter frequently while using the API, such as Addresses, Deliveries, Routes and Drivers.
Address
Addresses may be among the most basic data structures in any dispatch or routing system, it encodes the information about the destination of every delivery. Yet, if you take a look at it's data type, that can be found in the API reference for adding an address to the database, you can see, that it doesn't just include a regular postal address including contactfirstname
, contactlastname
, street
, housenumber
, postalcode
and city
, but also contact information like email
and phonenr
, which is used for customer notifications. Uncommon for human readable address information, but also part of the address data type and most important for the routing algorithms are the geo location.coordinate
s. These are so important, that they are added automatically for you, in case you don't set them explicitly. They are obtained from the address information in a similar manner as the geocode information endpoint. There's also one, for obtaining an address from a geolocation.
Of course it is possible to search through all added addresses in the database.
However, the most distinctive property of an address is the id
, used in particular as a reference from a delivery.
Delivery
The Delivery object may be considered the most central data structure of the whole API. It could also be a pickup. Central to it's definition is a supplierlocation_id
(where the delivery is picked up up), containing the mentioned reference id
of the address; and a deliverylocation_id
(where the delivery is brought to) which contains the id
of the end-customer address.
But as you can see, in the API reference, there's quite a bit more to it. The delivery object contains a whole bunch of time attributes, which are listed in the table below. Most notable are the pdt_from
and pdt_to
properties, which define the period of time when the delivery is planned planned, e.g. when an end customer is expected to be at home. It can be provided manually, and is necessary for timewindow routing. Most of the other time attributes are taken care of automatically and serve different purposes, e.g. the estimated time of arrival for customer notification.
Time Attributes for Delivery Objects
Abbrevation | Name | Description |
---|---|---|
PDT | planned delivery time | Input for planned delivery times based on customer needs or e.g. opening hours. |
TDT | target delivery time | Optimization result: Calculated (theoretically) possible time span of arrival time at the delivery location. |
DDT | driver delivery time | Time frame of predicted arrival time at the delivery location to be communicated to the driver (e.g. via a third-party telematics device). It is based on the originally calculated TDT. |
ETA | estimated time of arrival | Time span of predicted arrival time at the delivery location to be communicated to the end customer. |
ATA | actual time of arrival | Time of the driver's actual arrival at the customer's address (via driver's GPS position) |
ATD | actual time of delivery | Time of the driver's actual succesful delivery at the customer's address (timestamp of POST /deliverydone/{delivery_id}) |
PPT | planned pickup time | Manual input for a pickup based on customer wishes. |
ELS | estimated length of stay (minutes) | |
ALS | actual length of stay (minutes) | |
TFP | driving time from preceding delivery |
Other information that can be provided are some notes
from the dispatcher or load
information. The flag notify_customer
, that indicates whether the the customer should be notified before the package arrives. The delivery priority deliverprio
, which the routing algorithms can take advantage of. The creationtime
is added automatically, when the delivery is created. After the route is calculated the route_id
is assigned. The orderindex
, defining which delivery comes first, can be changed manually by calling order up and order down. In most cases, the orderindex
is solely defined by the optimal route calculated from the routing algorithm, but changing it manually can, for example, be useful for single routing
After the driver arrived at the customers address, he is supposed to update the status
via delivery done by a telematics device. Possible entries for status
can be found here. More detailed information of delivered packages can be set in the code
field. Possible entries can be found here. In case you prefer calling APIs to clicking web pages, you can get the same information (and a little more) by calling the endpoints delivery status and delivery code. Additional notes from the driver for a delivery are supposed to be written into the drivernotes
.
Basically all this data can modified by patching. You can of course get all data of sheduled deliveries, a specific delivery by ID or just the finished deliveries.
Last but not least, there's also a way for live end customers to track their deliveries live.
Like address id
s are used as a reference for deliveries, delivery id
s are used as references for routes.
Route
Now we get to the data structure we're actually here for - the route - which includes a sorted list of deliveries
, that is optimized by the Smartlane routing algorithms. But again, as you can see in the API reference there's quite a bit more to it, some meta data, as well as some stuff for convenience for front end developers.
Just like addresses and deliveries, routes have an id
; the creationtime
is inserted, as well. After the route is calculated, it includes the distance
of the whole route in meters, the net_duration
, which is the total driving time in minutes based on current on current traffic forecast and the gross_duration
, meaning the total time needed for the route including the driver's length of stays based on the els
(estimated length of stay) from the deliveries.
tst_from
and tst_to
define the target start time span, i.e. when the driver needs to start the route in distantcesorder to meet the targeted delivery times. The actual start time, ast
can also be set via the API. In case the driver is exchanged the previous_drivers
are saved in a list. The same holds for changed or canceled previous_deliveries
. When the whole route is updated, the IDs of the previous versions are stored in replaces
.
The routebase_address
, set by it's routebase_address_id
is the starting location of the route, in most cases the depot, but may be something different, e.g. for pickups. The routestring
is a GeoJSON LineString that includes a dense set of geo coordinates along the route, that can e.g. be used to display the route on a map. The areatext
contains a short auto generated description about the region of the route, like the cities through which the route goes.
The status
entry holds information like driverassigned
, canceled
or finished
. There is a list of all route stati, which can also be accessed via an API endpoint. Usually a dispatcher needs to assign a driver by setting the driver_id
. This is currently done via the patch route endpoint.
To save some bandwidth, one can get only the route meta data when details a not required.
As you may have already seen on the routing types page, there are a couple of different routing variants. You can find out, which one is suitable for a list of deliveries with an API endpoint. If you have an already calculated route, of course you can request the distances between subsequent deliveries.
For time window routing, it's sometimes beneficial to update the estimated time of arrivals so they include the most recent traffic forecasts. We also have quite a bit of stuff in the API to show the information about the location of routes on a map, e.g. areas of a route.
Updated 8 months ago