Smartlane API

The Smartlane API Developer Hub

Welcome to the Smartlane API developer hub. You'll find comprehensive guides and documentation to help you start working with the Smartlane API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

4. Tracking Actions

So far, we've given a brief introduction to the basics of our API, including our route optimization system. But this is only one side of our API, that may be associated with the up front planing process of the dispatcher. The other side, discussed in this chapter, may me associated with the actual operations of the drivers.

It allows for real time monitoring and supervision of the present operations process, which helps for on demand rescheduling based on the inevitable disruptions that happen out there on the road. And - probably even more important - this data can be mined for retrospective analysis of the transportation process and enables our algorithms to learn and take the past into account for future optimizations.

This data, provided by the trucks and connected third-party mobile devices (which are not provided by samrtlane), consists mainly of the status changes of the individual load, as well as the trucks position, which can be harvested by any telematics system connected to our API. The tracking entity is referrer by the Driver Entity.

First of all we need to create and register user accounts for the individual drivers, permitting access to transmit the relevant data.

Adding Drivers

While we start by showing how to add drivers via API, it may more convenient to add them via our web app and move on to the next point.

But it's also quite simple to post the necessary data to the API endpoint /driver

curl --request POST \
     --url "https://dispatch.smartlane.io/your_company_name/api/driver" \
     --header "Content-Type: application/json" \
     --header "Authorization: JWT your.Long_Randomfghxlcnebem.Secure_AccessToken" \
     --data '{"firstname":"John",  
              "lastname": "Driver",
              "email": "[email protected]",
              "mobilenr": "017012345678"}'
import requests

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

url = api_url + "/driver"

driver_data = {"firstname":"John",
               "lastname": "Driver",
               "email": "[email protected]",
               "mobilenr": "017012345678"}

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

If you see a response with HTML code 201 "Created", you know you've successfully added a new driver, along with your posted information and a couple of default values (e.g. the vehicle type "car").

{ "active": false,
  "company_id": null,
  "confirmed_at": null,
  "driveravailabilities": [],
  "email": "[email protected]",
  "expires": null,
  "firstname": "John",
  "htmlcolor": "0000ff",
  "id": 2,
  "lastname": "Driver",
  "mobilenr": "017012345678",
  "status": 0,
  "usertype": "driver",
  "vehicle": "car"
 }

More important than the direct response of the call to /driver, the call also triggers an email sent to the driver, which includes the activation code. (In addition, another email is sent to the dispatcher and another to Smartlane, for logging purposes.) That's necessary because routes can only be assigned to drivers that have been activated and, as you can see above, the "active" property is still set to false.

To activate the driver, you need to post the registration data to /registerdriver. The body of this post needs to include the 6 character activation code, sent in the email, as well as the drivers email identifier and the password, used for future authorization. Please note, that every email address can be registered only once, as it is the unique user identifier in our system.

curl --request POST \
     --url "https://dispatch.smartlane.io/your_company_name/api/registerdriver" \
     --header "Content-Type: application/json" \
     --header "Authorization: JWT your.Long_Randomfghxlcnebem.Secure_AccessToken" \
     --data 'data = {"email": "[email protected]",
                                   "password": "p4ssw0rd",
                                 "code": "A1234b"}
import requests

data = {"email": "[email protected]",
        "password": "p4ssw0rd",
        "code": "A1234b"}

url = api_url + "registerdriver"
response = requests.post(url, json=data)

When that's done, your driver should be registered

{"message": "driver successfully activated.",    "status": 200}

and you're ready to schedule some deliveries for him.

Assigning Drivers to Routes

After a route has been calculated, a driver can be assigned to it (or it gets assigned automatically if the assign_drivers url parameter has been set in the /calcroute/optimized/timewindow request). A driver can now be assigned by patching the `driver_id' to the ID of the desired driver, very much like in the example below. If it's assigned, the /currentdriverroute returns the freshly assigned route.

To make sure that the actual person who is assigned the ID also knows about the route, he must accept the tour. This can be done by updating the status of the route, from the default value 1 "assigned" to 2 "accepted". When the driver is actually in the car and starts the tour, his status is reported to the backend, and therefore also to the dispatcher, by setting the status to 3 "on the way". This is done in the same way, by patching the route via the API call /route/{route_id}.
Let's do this in just one step, to save some space:

curl --request PATCH \
     --url 'https://dispatch.smartlane.io/your_company_name/api/route/738' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: JWT your.Long_Randomfghxlcnebem.Secure_AccessToken' \
#    --data '{"status": 2}'    
     --data '{"status": 3}'
import requests

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

requrl = api_url + "route/738"

data = {"status": 2}
data = {"status": 3}

response = requests.patch(requrl, headers=auth_header, json=data)

Once the driver has reported he's "on the way", the target delivery times and potential delays are reevaluated in in short time intervals based on the driver's position and the current traffic forecast.

This real time predictions of the "estimated time of arrival" can optionally be used by our system, to notify the end customer via email or SMS about the delivery time, if notify_customer was set to true in the delivery information.

Updating the Status of Deliveries

After the driver has arrived at the customer's address, he is supposed to update the status via /deliverydone/delivery_id to either delivered or undelivered (or a couple of more options)

curl --request POST \
     --url 'https://dispatch.smartlane.io/your_company_name/api/deliverydone/421' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: JWT your.Long_Randomfghxlcnebem.Secure_AccessToken' \
     --data '{"status": "deliverd",
              "drivernotes": "Optional notes from the driver."}'
import requests

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

requrl = api_url + "deliverydone/1" # 1 is delivery_id

data = {"status": "delivered"
        "drivernotes": "Optional notes from the driver."}

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

In the same way, the driver is expected to make the deliveries and report their status until he has completed the whole tour. If a package couldn't be delivered, it will automatically be placed back on the list of undelivered entries, ready to be reassigned to the next tour.

Updated 2 months ago

4. Tracking Actions


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.