Introduction

The Dispatching API (DAS) is an HTTP JSON REST API, that automatically assigns orders and plans routes. The API is customizable according to individual requirements and is functional in Germany, Portugal and the United Kingdom. Visit our tutorials or videos for more information on use cases.

The Dispatching API request inputs are divided into the following sections:

Orders: The orders section defines the identity and location of individual orders as well as their buffer and priority variables. The buffer value represents the time in minutes each order takes to complete. The worth of an order is a numeric value that can represent anything between a priority level to a monetary value.
Drivers: The driver input defines the identity and location of the individual drivers.
Index: The index section defines by which criteria (distance, duration and worth) the orders shall be divided among the drivers and how the route planning shall be structured.
Capacity: The section includes a variable that defines the maximum number of orders, that should be assigned to a single driver.

The Dispatching API response is divided into the following sections:

Trips: This section includes all the information related to the computed trips. Each individual trip consists of a summary section with various datapoints (e.g. total trip distance/duration, polylines), the assigned driver and the individual orders (e.g. arrival/departure times).
Unassigned Orders: All orders, which were not assigned to a driver can be found in this response section.
Index: The index section provides a reference on what values were used for the computation of the trips.
Constraints: This section mimics and provide a reminder for the values that given during the request.

Get in touch to find out more on how to automate your fleet management processes.

Calculate Batch

POST https://www.synertics.io/dispatching/batch/

Apply this method to automatically assign orders to drivers according to individual preferences.

Request

Body

orders

An order object consists of

identification string required

unique identifier to distinguish orders

longitude float required

longitude of the order

latitude float required

latitude of the order

buffer float optional Default: 300

time in seconds to complete an order

worth float optional Default: 0

numeric value that can represent anything between a priority level to a monetary value

drivers

A driver object consists of

identification string required

unique identifier to distinguish drivers

longitude float required

longitude of the driver

latitude float required

latitude of the driver

index

A index object is made of factors with values ranging between 0 and 1, representing the % by which the individual factors are prioritized in comparison to each other

distance_index float optional Default: 50

distance priority level

duration_index float optional Default: 50

duration priority level

worth_index float optional Default: 0

worth priority level

constraints

A constraints object consists of

max_orders_per_driver integer optional Maximum: 50

Maximum number of orders allowed per driver.

start_time float optional current time

time(UTC) in Unix format at which the driver(s) shall leave the starting location.

Response

Body

id string

unique identifier generated by the API to distinguish batches

trips list

list of all computed trips

id string

unique identifier generated by the API to distinguish trips

orders list

list of all assigned orders to a specific trip

id string

unique identifier generated by the API to distinguish orders

identification string

unique identifier generated by the user to distinguish orders

longitude float

longitude of the order

latitude float

latitude of the order

buffer float

time in seconds to complete an order

worth float

numeric value that can represent anything between a priority level to a monetary value

duration float

duration in seconds for the driver to reach order coming from its previous location

distance float

distance in meters for the driver to reach order coming from its previous location

start_time float

time(UTC) in unix format at which the driver is expected to leave for the order

arrival_time float

time(UTC) in unix format at which the driver is expected to arrive at the order

end_time float

time(UTC) in unix format at which the driver is expected to leave the order

stop_id Int

the position within a sequence of a trip in which the order is expected to be completed

total_duration float

total duration in second of a trip

total_distance float

total distance in meters of a trip

start_time float

start time(UTC) of a trip in unix format

end_time float

end time(UTC) of a trip in unix format

polyline string

trip structure encoded in flexible polyline

batch string

Id of the batch to which the trip belongs to

driver object

driver to whom a trip is assigned

id string required

unique identifier generated by the API to distinguish drivers

identification string required

unique identifier generated by the user to distinguish drivers

longitude float required

longitude of the driver

latitude float required

latitude of the driver

unassigned_orders list

list of orders that were not assigned to any driver.

identification string

unique identifier generated by the user to distinguish orders

longitude float

longitude of the order

latitude float

latitude of the order

buffer float

time in seconds to complete an order

worth float

numeric value that can represent anything between a priority level to a monetary value

index object

prioritization level of individual factors

distance_index float

distance priority level

duration_index float

duration priority level

worth_index float

worth priority level

constraints object

constraint conditions applied in the algorithm decision making process

max_orders_per_driver integer

maximum number of order to be assigned to a single driver

start_time float

time(UTC) in Unix format at which the driver(s) shall leave the starting location.

Example: Request in Python


import requests
import json

url = "https://www.synertics.io/dispatching/batch/"

APIKey = 'Your API Key'

payload = json.dumps({
    "orders": [
    {
        "identification": 1,
        "latitude": 48.15184573538307,
        "longitude": 11.627787769196722,
        "buffer": 30,
        "worth": 20
    },
    {
        "identification": 2,
        "latitude": 48.128796973432905,
        "longitude": 11.511432867285613,
        "buffer": 30,
        "worth": 40
    }
    ,
    {
        "identification": 3,
        "latitude": 48.07018403305119, 
        "longitude": 11.612210183222194,
        "buffer": 30,
        "worth": 40
    }
    ],
    "drivers": [
    {
        "identification": 1,
        "latitude": 48.11463798463605,
        "longitude": 11.646685844839068
    }
    ],
    "index":
    {
        "distance_index": 40,
        "duration_index": 40,
        "worth_index": 20
    }
    ,
    "constraints":{
        "max_orders_per_driver": 2 
    }
})

headers = {
    'Authorization': f'TOKEN {APIKey}',                                     
    'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Example: Response in JSON

{
    "id": "e77_7b_c1f2_2340e8b8b3957",
    "trips": [
        {
        "id": "d__1fd77884_2e_f41ba6_118",
        "orders": [
            {
            "id": "bd4c602b_c_2bd13e0_f1456d",
            "start_time": 1646722800.0,
            "end_time": 1646723475.9,
            "arrival_time": 1646723445.9,
            "stop_id": 1,
            "identification": "1",
            "buffer": 30.0,
            "latitude": 48.15184573538307,
            "longitude": 11.627787769196722,
            "worth": 20.0,
            "duration": 645.9,
            "distance": 6966.8
            },
            {
            "id": "e055d983650116618b4d2afc8",
            "start_time": 1646723475.9,
            "end_time": 1646724507.7,
            "arrival_time": 1646724477.7,
            "stop_id": 2,
            "identification": "3",
            "buffer": 30.0,
            "latitude": 48.07018403305119,
            "longitude": 11.612210183222194,
            "worth": 40.0,
            "duration": 1001.8,
            "distance": 12313.0
            }
        ],
        "driver": {
            "id": "7_2e28ff4d1dbcafb050c1a5b",
            "identification": "1",
            "latitude": 48.11463798463605,
            "longitude": 11.646685844839068
        },
        "total_duration": 1707.7000000476837,
        "total_distance": 19279.8,
        "start_time": 1646722800.0,
        "end_time": 1646724507.7,
        "polyline": "BFi3inC2s1lJXpBNE3CkBjCYPG5BW9CiBzBOVIXCdBRFRFRNjEwCfUtCuBxCyBjB......",
        "batch":"e77_7b_c1f2_2340e8b8b3957"
        }
    ],
    "index": {
        "distance_index": 40.0,
        "duration_index": 40.0,
        "worth_index": 20.0
    },
    "constraints": {
        "max_orders_per_driver": 2
    },
    "unassigned_orders": [
        {
        "identification": "2",
        "buffer": 30.0,
        "latitude": 48.128796973432905,
        "longitude": 11.511432867285613,
        "worth": 40.0
        }
    ]
}

Retrieve all batches

GET https://www.synertics.io/dispatching/batch/

This method fetches all batches, that have been saved in the API's database.

Responses

Body

id string

unique identifier generated by the API to distinguish batches

trips list

list of all computed trips

id string

unique identifier generated by the API to distinguish trips

orders list

list of all assigned orders to a specific trip

id string

unique identifier generated by the API to distinguish orders

identification string

unique identifier generated by the user to distinguish orders

longitude float

longitude of the order

latitude float

latitude of the order

buffer float

time in seconds to complete an order

worth float

numeric value that can represent anything between a priority level to a monetary value

duration float

duration in seconds for the driver to reach order coming from its previous location

distance float

distance in meters for the driver to reach order coming from its previous location

start_time float

time(UTC) in unix format at which the driver is expected to leave for the order

arrival_time float

time(UTC) in unix format at which the driver is expected to arrive at the order

end_time float

time(UTC) in unix format at which the driver is expected to leave the order

stop_id Int

the position within a sequence of a trip in which the order is expected to be completed

total_duration float

total duration in second of a trip

total_distance float

total distance in meters of a trip

start_time float

start time(UTC) of a trip in unix format

end_time float

end time(UTC) of a trip in unix format

polyline string

trip structure encoded in flexible polyline

batch string

Id of the batch to which the trip belongs to

driver object

driver to whom a trip is assigned

id string required

unique identifier generated by the API to distinguish drivers

identification string required

unique identifier generated by the user to distinguish drivers

longitude float required

longitude of the driver

latitude float required

latitude of the driver

unassigned_orders list

list of orders that were not assigned to any driver.

identification string

unique identifier generated by the user to distinguish orders

longitude float

longitude of the order

latitude float

latitude of the order

buffer float

time in seconds to complete an order

worth float

numeric value that can represent anything between a priority level to a monetary value

index object

prioritization level of individual factors

distance_index float

distance priority level

duration_index float

duration priority level

worth_index float

worth priority level

constraints object

constraint conditions applied in the algorithm decision making process

max_orders_per_driver integer

maximum number of order to be assigned to a single driver

start_time float

time(UTC) in Unix format at which the driver(s) shall leave the starting location.

Example: Request in Python

import requests

url = "https://www.synertics.io/dispatching/batch/"

APIKey = 'Your API Key'

payload = ""
headers = {
    'Authorization': f'TOKEN {APIKey}',  
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Example: Response in JSON

[
    {
        "id": "e77_7b_c1f2_2340e8b8b3957",
        "trips": [
            {
            "id": "d__1fd77884_2e_f41ba6_118",
            "orders": [
                {
                "id": "bd4c602b_c_2bd13e0_f1456d",
                "start_time": 1646722800.0,
                "end_time": 1646723475.9,
                "arrival_time": 1646723445.9,
                "stop_id": 1,
                "identification": "1",
                "buffer": 30.0,
                "latitude": 48.15184573538307,
                "longitude": 11.627787769196722,
                "worth": 20.0,
                "duration": 645.9,
                "distance": 6966.8
                },
                {
                "id": "e055d983650116618b4d2afc8",
                "start_time": 1646723475.9,
                "end_time": 1646724507.7,
                "arrival_time": 1646724477.7,
                "stop_id": 2,
                "identification": "3",
                "buffer": 30.0,
                "latitude": 48.07018403305119,
                "longitude": 11.612210183222194,
                "worth": 40.0,
                "duration": 1001.8,
                "distance": 12313.0
                }
            ],
            "driver": {
                "id": "7_2e28ff4d1dbcafb050c1a5b",
                "identification": "1",
                "latitude": 48.11463798463605,
                "longitude": 11.646685844839068
            },
            "total_duration": 1707.7000000476837,
            "total_distance": 19279.8,
            "start_time": 1646722800.0,
            "end_time": 1646724507.7,
            "polyline": "BFi3inC2s1lJXpBNE3CkBjCYPG5BW9CiBzBOVIXCdBRFRFRNjEwCfUtCuBxCyBjB......",
            "batch":"e77_7b_c1f2_2340e8b8b3957"
            }
        ],
        "index": {
            "distance_index": 40.0,
            "duration_index": 40.0,
            "worth_index": 20.0
        },
        "constraints": {
            "max_orders_per_driver": 2
        },
        "unassigned_orders": [
            {
            "identification": "2",
            "buffer": 30.0,
            "latitude": 48.128796973432905,
            "longitude": 11.511432867285613,
            "worth": 40.0
            }
        ]
    },
    .
    .
    .
    .
]

Retreive a Batch

GET https://www.synertics.io/dispatching/batch/batch_ID/

*a batch_ID is an identification unique to a specific batch

This method fetches a specific batch, that has been saved in the API's database.

Responses

Body

id string

unique identifier generated by the API to distinguish batches

trips list

list of all computed trips

id string

unique identifier generated by the API to distinguish trips

orders list

list of all assigned orders to a specific trip

id string

unique identifier generated by the API to distinguish orders

identification string

unique identifier generated by the user to distinguish orders

longitude float

longitude of the order

latitude float

latitude of the order

buffer float

time in seconds to complete an order

worth float

numeric value that can represent anything between a priority level to a monetary value

duration float

duration in seconds for the driver to reach order coming from its previous location

distance float

distance in meters for the driver to reach order coming from its previous location

start_time float

time(UTC) in unix format at which the driver is expected to leave for the order

arrival_time float

time(UTC) in unix format at which the driver is expected to arrive at the order

end_time float

time(UTC) in unix format at which the driver is expected to leave the order

stop_id Int

the position within a sequence of a trip in which the order is expected to be completed

total_duration float

total duration in second of a trip

total_distance float

total distance in meters of a trip

start_time float

start time(UTC) of a trip in unix format

end_time float

end time(UTC) of a trip in unix format

polyline string

trip structure encoded in flexible polyline

batch string

Id of the batch to which the trip belongs to

driver object

driver to whom a trip is assigned

id string required

unique identifier generated by the API to distinguish drivers

identification string required

unique identifier generated by the user to distinguish drivers

longitude float required

longitude of the driver

latitude float required

latitude of the driver

unassigned_orders list

list of orders that were not assigned to any driver.

identification string

unique identifier generated by the user to distinguish orders

longitude float

longitude of the order

latitude float

latitude of the order

buffer float

time in seconds to complete an order

worth float

numeric value that can represent anything between a priority level to a monetary value

index object

prioritization level of individual factors

distance_index float

distance priority level

duration_index float

duration priority level

worth_index float

worth priority level

constraints object

constraint conditions applied in the algorithm decision making process

max_orders_per_driver integer

maximum number of order to be assigned to a single driver

start_time float

time(UTC) in Unix format at which the driver(s) shall leave the starting location.

Example: Request in Python

import requests

trip_ID = 'trip_ID'

APIKey = 'Your API Key'

url = f'https://www.synertics.io/dispatching/batch/{batch_ID}/'  

payload = ""
headers = {
    'Authorization': f'TOKEN {APIKey}', 
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Example: Response in JSON

{
    "id": "e77_7b_c1f2_2340e8b8b3957",
    "trips": [
        {
        "id": "d__1fd77884_2e_f41ba6_118",
        "orders": [
            {
            "id": "bd4c602b_c_2bd13e0_f1456d",
            "start_time": 1646722800.0,
            "end_time": 1646723475.9,
            "arrival_time": 1646723445.9,
            "stop_id": 1,
            "identification": "1",
            "buffer": 30.0,
            "latitude": 48.15184573538307,
            "longitude": 11.627787769196722,
            "worth": 20.0,
            "duration": 645.9,
            "distance": 6966.8
            },
            {
            "id": "e055d983650116618b4d2afc8",
            "start_time": 1646723475.9,
            "end_time": 1646724507.7,
            "arrival_time": 1646724477.7,
            "stop_id": 2,
            "identification": "3",
            "buffer": 30.0,
            "latitude": 48.07018403305119,
            "longitude": 11.612210183222194,
            "worth": 40.0,
            "duration": 1001.8,
            "distance": 12313.0
            }
        ],
        "driver": {
            "id": "7_2e28ff4d1dbcafb050c1a5b",
            "identification": "1",
            "latitude": 48.11463798463605,
            "longitude": 11.646685844839068
        },
        "total_duration": 1707.7000000476837,
        "total_distance": 19279.8,
        "start_time": 1646722800.0,
        "end_time": 1646724507.7,
        "polyline": "BFi3inC2s1lJXpBNE3CkBjCYPG5BW9CiBzBOVIXCdBRFRFRNjEwCfUtCuBxCyBjB......",
        "batch":"e77_7b_c1f2_2340e8b8b3957"
        }
    ],
    "index": {
        "distance_index": 40.0,
        "duration_index": 40.0,
        "worth_index": 20.0
    },
    "constraints": {
        "max_orders_per_driver": 2
    },
    "unassigned_orders": [
        {
        "identification": "2",
        "buffer": 30.0,
        "latitude": 48.128796973432905,
        "longitude": 11.511432867285613,
        "worth": 40.0
        }
    ]
}

Retrieve all Trips

GET https://www.synertics.io/dispatching/trips/

This method fetches all trips, that have been saved in the API's database.

Responses

Body

id string

unique identifier generated by the API to distinguish trips

orders list

list of all assigned orders to a specific trip

id string

unique identifier generated by the API to distinguish orders

identification string

unique identifier generated by the user to distinguish orders

longitude float

longitude of the order

latitude float

latitude of the order

buffer float

time in seconds to complete an order

worth float

numeric value that can represent anything between a priority level to a monetary value

duration float

duration in seconds for the driver to reach order coming from its previous location

distance float

distance in meters for the driver to reach order coming from its previous location

start_time float

time(UTC) in unix format at which the driver is expected to leave for the order

arrival_time float

time(UTC) in unix format at which the driver is expected to arrive at the order

end_time float

time(UTC) in unix format at which the driver is expected to leave the order

stop_id Int

the position within a sequence of a trip in which the order is expected to be completed

total_duration float

total duration in second of a trip

total_distance float

total distance in meters of a trip

start_time float

start time(UTC) of a trip in unix format

end_time float

end time(UTC) of a trip in unix format

polyline string

trip structure encoded in flexible polyline

driver object

driver to whom a trip is assigned

id string

unique identifier generated by the API to distinguish drivers

identification string

unique identifier generated by the user to distinguish drivers

longitude float

longitude of the driver

latitude float

latitude of the driver

Example: Request in Python

import requests

url = "https://www.synertics.io/dispatching/trips/"

APIKey = 'Your API Key'

payload = ""
headers = {
    'Authorization': f'TOKEN {APIKey}',  
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Example: Response in JSON

[
    {
        "id": "d__1fd77884_2e_f41ba6_118",
        "orders": [
            {
            "id": "bd4c602b_c_2bd13e0_f1456d",
            "start_time": 1646722800.0,
            "end_time": 1646723475.9,
            "arrival_time": 1646723445.9,
            "stop_id": 1,
            "identification": "1",
            "buffer": 30.0,
            "latitude": 48.15184573538307,
            "longitude": 11.627787769196722,
            "worth": 20.0,
            "duration": 645.9,
            "distance": 6966.8
            },
            {
            "id": "e055d983650116618b4d2afc8",
            "start_time": 1646723475.9,
            "end_time": 1646724507.7,
            "arrival_time": 1646724477.7,
            "stop_id": 2,
            "identification": "3",
            "buffer": 30.0,
            "latitude": 48.07018403305119,
            "longitude": 11.612210183222194,
            "worth": 40.0,
            "duration": 1001.8,
            "distance": 12313.0
            }
        ],
        "driver": {
            "id": "7_2e28ff4d1dbcafb050c1a5b",
            "identification": "1",
            "latitude": 48.11463798463605,
            "longitude": 11.646685844839068
        },
        "total_duration": 1707.7000000476837,
        "total_distance": 19279.8,
        "start_time": 1646722800.0,
        "end_time": 1646724507.7,
        "polyline": "BFi3inC2s1lJXpBNE3C......",
        "batch":"e77_7b_c1f2_2340e8b8b3957"
    },
    .
    .
    .
    .
]

Retreive a Trip

GET https://www.synertics.io/dispatching/trips/trip_ID/

*a trip_ID is an identification unique to a specific trip

This method fetches a specific trip, that has been saved in the API's database.

Responses

Body

id string

unique identifier generated by the API to distinguish trips

orders list

list of all assigned orders to a specific trip

id string

unique identifier generated by the API to distinguish orders

identification string

unique identifier generated by the user to distinguish orders

longitude float

longitude of the order

latitude float

latitude of the order

buffer float

time in seconds to complete an order

worth float

numeric value that can represent anything between a priority level to a monetary value

duration float

duration in seconds for the driver to reach order coming from its previous location

distance float

distance in meters for the driver to reach order coming from its previous location

start_time float

time(UTC) in unix format at which the driver is expected to leave for the order

arrival_time float

time(UTC) in unix format at which the driver is expected to arrive at the order

end_time float

time(UTC) in unix format at which the driver is expected to leave the order

stop_id Int

the position within a sequence of a trip in which the order is expected to be completed

total_duration float

total duration in second of a trip

total_distance float

total distance in meters of a trip

start_time float

start time(UTC) of a trip in unix format

end_time float

end time(UTC) of a trip in unix format

polyline string

trip structure encoded in flexible polyline

driver object

driver to whom a trip is assigned

id string >

unique identifier generated by the API to distinguish drivers

identification string

unique identifier generated by the user to distinguish drivers

longitude float

longitude of the driver

latitude float

latitude of the driver

Example: Request in Python

import requests

trip_ID = 'trip_ID'

APIKey = 'Your API Key'

url = f'https://www.synertics.io/dispatching/trips/{trip_ID}/'  

payload = ""
headers = {
    'Authorization': f'TOKEN {APIKey}', 
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Example: Response in JSON

{
    "id": "d__1fd77884_2e_f41ba6_118",
    "orders": [
        {
        "id": "bd4c602b_c_2bd13e0_f1456d",
        "start_time": 1646722800.0,
        "end_time": 1646723475.9,
        "arrival_time": 1646723445.9,
        "stop_id": 1,
        "identification": "1",
        "buffer": 30.0,
        "latitude": 48.15184573538307,
        "longitude": 11.627787769196722,
        "worth": 20.0,
        "duration": 645.9,
        "distance": 6966.8
        },
        {
        "id": "e055d983650116618b4d2afc8",
        "start_time": 1646723475.9,
        "end_time": 1646724507.7,
        "arrival_time": 1646724477.7,
        "stop_id": 2,
        "identification": "3",
        "buffer": 30.0,
        "latitude": 48.07018403305119,
        "longitude": 11.612210183222194,
        "worth": 40.0,
        "duration": 1001.8,
        "distance": 12313.0
        }
    ],
    "driver": {
        "id": "7_2e28ff4d1dbcafb050c1a5b",
        "identification": "1",
        "latitude": 48.11463798463605,
        "longitude": 11.646685844839068
    },
    "total_duration": 1707.7000000476837,
    "total_distance": 19279.8,
    "start_time": 1646722800.0,
    "end_time": 1646724507.7,
    "polyline": "BFi3inC2s1lJXpBNE3C......",
    "batch":"e77_7b_c1f2_2340e8b8b3957"
}

Dispatching

Disposition

Dispatching API

Disposition API

Tutorials

Videos

Introduction

Calculate Batch

Request

Body

orders

drivers

index

constraints

Response

Body

Example: Request in Python

Example: Response in JSON

Retrieve all batches

Responses

Body

Example: Request in Python

Example: Response in JSON

Retreive a Batch

Responses

Body

Example: Request in Python

Example: Response in JSON

Retrieve all Trips

Responses

Body

Example: Request in Python

Example: Response in JSON

Retreive a Trip

Responses

Body

Example: Request in Python

Example: Response in JSON