Basic API Data Structures

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.coordinates. 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

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 ids are used as a reference for deliveries, delivery ids 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.