Getting results

The planning result can be retrieved by the following options:

  • Process status (id)
  • Route
  • Route (id)
  • Route metadata
  • Route metadata (id)

Process status (id)

One option to check the status of the planning is the Process status (id).

import requests

auth_header = {"Authorization": 'JWT ' + token}
api_url = "https://<your company name>.prd.smartlane.io/api/process/status/'your_process_id'"

response = requests.get(api_url, headers=auth_header)
print (response.text)

This call returns the current status of an asynchroneous routing process. It should look like this:

{'process_id': 'd0063042-cb15-11e8-9707-0242ac130003',
 'progress': 0.1,
 'state': 'PENDING',
 'task': None}

The attribute {state} indicates if an optimization is still running ('PENDING'). When the process is finished, the state is either 'SUCCESS' or 'FAILURE'. So let's take a look at a successful response first.

Successful Routing

{'data': {'failed_addresses': [],
             'message': '',
             'min_tour_start': '2022-07-03TT15:57:39.727+02:00',
             'notes': [],
             'route_ids': [1],
             'route_objects': [],
             'success': True,
             'successful_routes': 1,
             'unsuccessful_deliveries': []},
 'process_id': 'd0063042-cb15-11e8-9707-0242ac130003',
 'progress': 1.0,
 'state': 'SUCCESS',
 'task': None}

The most important information is the list of route_ids which you can use to request the full information about the routes via the Route (id) endpoint.

The data sections provides details of the optimization result:

failed_addresses: This can happen e.g. due to failed geo-coding of the addresses

unsuccessful_deliveries: Is the container for shipments that have been dropped because they did not meet the constraints for various reasons.

notes: Will help you understand why shipments failed.

Unsuccessful Routing

Sometimes the routing process cannot provide a proper solution and is therefore considered a FAILURE. This can be due to different reasons.

Sometimes, especially when users are just starting to get familiar with the API, errors arise because unprocessable input is provided. We're putting in quite a bit effort, to make our API as fault tolerant as possible. But sometimes rigor is required to avoid ambiguity. In this case we usually provide an err_id with a corresponding human readable message.

Sometimes it's not possible to calculate a route under the given constraints, even if formally valid input is provided. Just think about an obvious example: If two deliveries are supposed to be shipped to two cities hours away from each other within very narrow time windows, the driver just cannot arrive in time. Our policy here is generally to rather not provide a route, than one that is not feasible in practice. In this case it's hard for the algorithm to decide, which constrains are the cause of the failure, but do our best to provide hints in a message as well as structured data, about the constrains that should be reconsidered (no doubt, with enough vehicles everything schedule is possible).

Yet, every once in a while, errors emerge that we haven't even considered. In this case we have to fall back to rather general error messages, but we're always happy provide support and learn more about your specific use case.

Route

The call to Route returns all data for all planned routes from the system.

import requests

auth_header = {"Authorization": 'JWT ' + token}
api_url = "https://<your company name>.prd.smartlane.io/api/route"

response = requests.get(api_url, headers=auth_header)
print (response.text)

The response should look something like this:

{
    "ast": null,
    "creationtime": "2022-07-27T14:19:42.078012+00:00",
    "custom_id": "id_1",
    "deliveries": [
        {
            "address": {
                "addresstype": null,
                "city": "München",
                "contactcompany": "customer_1",
                "contactfirstname": null,
                "contactlastname": null,
                "customernr": null,
                "district": "Schwabing",
                "housenumber": "8",
                "id": 2,
                "phonenr": null,
                "postalcode": "80804",
                "street": "kraepelinstr."
            },
            "ata": null,
            "atd": null,
            "custom_id": "D_0006",
            "custom_tour": null,
            "ddt_from": "2025-04-03T06:00:00.802480+00:00",
            "ddt_to": "2025-04-03T06:01:00.802480+00:00",
            "deliverprio": "low",
            "delivery_delay": 0,
            "delivery_interval": [
                "2025-04-03T06:00:00.802480+00:00",
                "2025-04-03T06:02:00.802480+00:00"
            ],
            "effective_loads": [
                -5000,
                -1000,
                -2000
            ],
            "els": 2,
            "els_seconds": 120,
            "eta_from": "2025-04-03T06:00:00.802480+00:00",
            "eta_interval": [
                "2025-04-03T06:00:00.802480+00:00",
                "2025-04-03T06:20:00.802480+00:00"
            ],
            "eta_to": "2025-04-03T06:20:00.802480+00:00",
            "height": null,
            "id": 1,
            "length": null,
            "load": -5000,
            "load_2": -1000,
            "load_3": -2000,
            "load_class": null,
            "multi": null,
            "notes": null,
            "order_in_tour": 1,
            "orderindex": 1,
            "pdt_from": "2025-04-03T06:00:00+00:00",
            "pdt_to": "2025-04-03T14:00:00+00:00",
            "pickup_id": null,
            "pickup_ref_id": null,
            "product_code": "None",
            "same_stop_unit": null,
            "shipment_type": "delivery",
            "status": 1,
            "status_color": "c1d2d7",
            "tdt_from": "2025-04-03T06:00:00.802480+00:00",
            "tdt_to": "2025-04-03T06:00:00.802480+00:00",
            "territory": null,
            "tfp": 23,
            "tfp_seconds": 1413,
            "unit": null,
            "waiting_time": 0.0,
            "waiting_time_seconds": 0,
            "width": null
        },
        {
            "address": {
                "addresstype": null,
                "city": "München",
                "contactcompany": "customer_2",
                "contactfirstname": null,
                "contactlastname": null,
                "customernr": null,
                "district": "Milbertshofen",
                "housenumber": "9",
                "id": 3,
                "phonenr": null,
                "postalcode": "80809",
                "street": "am oberwiesenfeld"
            },
            "ata": null,
            "atd": null,
            "custom_id": "id_2",
            "custom_tour": null,
            "ddt_from": "2025-04-03T06:15:00.802480+00:00",
            "ddt_to": "2025-04-03T06:16:00.802480+00:00",
            "deliverprio": "medium",
            "delivery_delay": 0,
            "delivery_interval": [
                "2025-04-03T06:15:00.802480+00:00",
                "2025-04-03T06:17:00.802480+00:00"
            ],
            "effective_loads": [
                6000,
                900,
                0
            ],
            "els": 2,
            "els_seconds": 120,
            "eta_from": "2025-04-03T06:15:00.802480+00:00",
            "eta_interval": [
                "2025-04-03T06:15:00.802480+00:00",
                "2025-04-03T06:35:00.802480+00:00"
            ],
            "eta_to": "2025-04-03T06:35:00.802480+00:00",
            "height": null,
            "id": 2,
            "length": null,
            "load": 6000,
            "load_2": 900,
            "load_3": 0,
            "load_class": null,
            "multi": null,
            "notes": null,
            "order_in_tour": 2,
            "orderindex": 2,
            "pdt_from": "2025-04-03T06:00:00+00:00",
            "pdt_to": "2025-04-03T14:00:00+00:00",
            "pickup_id": null,
            "pickup_ref_id": null,
            "product_code": "None",
            "same_stop_unit": null,
            "shipment_type": "pickup",
            "status": 1,
            "status_color": "c1d2d7",
            "tdt_from": "2025-04-03T06:15:00.802480+00:00",
            "tdt_to": "2025-04-03T06:15:00.802480+00:00",
            "territory": null,
            "tfp": 12,
            "tfp_seconds": 725,
            "unit": null,
            "waiting_time": 0.9166666666666666,
            "waiting_time_seconds": 55,
            "width": null
        }
    ],
    "distance": 11570,
    "finished_deliveries": 0,
    "fixed_cost": 250.0,
    "gross_duration": 3543,
    "id": 1,
    "initial_creationtime": "2022-07-27T14:19:42.078045+00:00",
    "locked": false,
    "net_duration": 3248,
    "performed_breaks": {
        "rest_break_items": []
    },
    "previous_deliveries": null,
    "remaining_time": 0,
    "return_time": "2025-04-03T06:35:30.802480+00:00",
    "roundtrip": false,
    "routebase_address_id": 1,
    "status": 0,
    "total_cost": "254.05",
    "total_deliveries": 2,
    "total_driving_time_seconds": 3248,
    "total_load": 1000,
    "total_load_2": -100,
    "total_load_3": -2000,
    "total_loads": [
        1000,
        -100,
        -2000
    ],
    "total_stop_time": 4,
    "total_waiting_time": 0,
    "total_waiting_time_seconds": 55,
    "tour_delay": 0,
    "tst_from": "2025-04-03T05:36:27.802480+00:00",
    "tst_to": "2025-04-03T06:06:27.802480+00:00",
    "variable_cost": 4.0495,
    "vehicle": "truck",
    "vehicle_id": 1,
    "waiting_cost": 0.0
}

Again, the most important information is the list of route_ids which you can use to request the full information about the routes via the Route (id) endpoint.

Route (id)

The call to Route (id) returns all data for one specific planned route from the system.

import requests

auth_header = {"Authorization": 'JWT ' + token}
api_url = "https://<your company name>.prd.smartlane.io/api/route/'your_route_id"

response = requests.get(api_url, headers=auth_header)
print (response.text)

Route metadata

The call to Route metadata returns a reduced set of data (without route geometry) for planned routes from the system.

import requests

auth_header = {"Authorization": 'JWT ' + token}
api_url = "https://<your company name>.prd.smartlane.io/api/routemetadata"

response = requests.get(api_url, headers=auth_header)
print (response.text)

Posting this call will return this response:

{
    "num_results": 1,
    "objects": [
        {
            "id": 1,
            "creationtime": "2022-07-27T14:19:42.078012+00:00",
            "initial_creationtime": "2022-07-27T14:19:42.078045+00:00",
            "net_duration": 3248,
            "gross_duration": 3543,
            "distance": 11570,
            "status": 0,
            "routebase_address_id": 1,
            "tst_from": "2025-04-03T05:36:27.802480+00:00",
            "tst_to": "2025-04-03T06:06:27.802480+00:00",
            "ast": null,
            "custom_id": "id_1",
            "deliveries": [
                1,
                2
            ],
            "total_load": 1000
        }
    ]
}

Route metadata (id)

The call to Route metadata (id) returns a reduced set of data (without geometry) for one specific planned route from the system.

import requests

auth_header = {"Authorization": 'JWT ' + token}
api_url = "https://<your company name>.prd.smartlane.io/api/routemetadata/'your_route_id"

response = requests.get(api_url, headers=auth_header)
print (response.text)

The response should look something like this:

{
    "id": 1,
    "creationtime": "2022-07-27T14:19:42.078012+00:00",
    "net_duration": 3248,
    "gross_duration": 3543,
    "distance": 11570,
    "total_loads": [
        1000,
        -100,
        -2000
    ],
    "status": 0,
    "routebase_address_id": 1,
    "tst_from": "2025-04-03T05:36:27.802480+00:00",
    "tst_to": "2025-04-03T06:06:27.802480+00:00",
    "ast": null,
    "custom_id": "id_1",
    "deliveries": [
        1,
        2
    ],
    "total_load": 1000,
    "tour_start_time": "2025-04-03T05:36:27.802480+00:00"
}