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 in the driver's App. 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, is when the driver hits a start button in the driver's app. 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.

Driver

So you have an automatic route planing system, but what would it be good for without a driver? The driver, like the dispatcher is considered a user in the system.

They are distinct by the usertype, which can be driver or dispatcher (or admin as a third option) and share a couple of properties: id, firstname, lastname, email, company_id, active, confirmed_at (the activation process is illustrated on the getting started page), as well as when the authentication token expires.

Exclusive to the driver is the mobile_nr, the vehicle type (which can be car, truck, bike or walk) and an htmlcolor to ensure consistency in the front end (e.g. when a driver is shown on the map).

Of course, you can get a list of all drivers or modify them. Pleaso note that at the moment, you cannot delete drivers because of potential references to tracking data or tour assignments.

After the driver let's the system know, when he is available via his app, the dispatcher can also ask for this information. The driver is supposed to update his position (a geo location with a time stamp) frequently, too, so that the dispatcher can get e.g. the current positions of all drivers or the trace (polyline) of the already driven part of a route.