Scheduled Routes API Documentation

#

Introduction #

Welcome to our Routing and Scheduling API user manual!

v1.1 added support for route Templates
v1.2 added support for flexible vehicle capacity configuration

Our API is engineered to enhance route planning and scheduling for vehicle fleets, addressing key constraints such as service time windows, capacity limits, and traffic conditions. By leveraging our API, businesses can significantly improve delivery efficiency, reduce operational costs, and save valuable time through optimized routing and scheduling solutions.

At its core, the API solves the Vehicle Routing Problem (VRP) with pickup and delivery. This problem involves calculating the most efficient routes for a fleet to visit multiple locations to perform pickup and delivery tasks while meeting constraints like time windows, vehicle capacity, and availability.

Additionally, our API supports dynamic schedule adjustments or re-optimization. If you need to modify an existing schedule—whether due to new orders, cancellations, or other changes—you can provide an updated picture of your schedule by specifying the job statuses and vehicle locations. The API will then re-optimize the schedule to reflect these changes, ensuring continuous efficiency in your operations.

For information on how to quickly get ready and start using the API, see Get Started. Several quick tutorials are also provided in the “Tutorials” section.

Get Started #

The API offers two key methods for managing routing and scheduling optimization:

Optimization POST – Use this method to submit a routing and scheduling optimization problem. After submitting a POST method, you will receive a unique reference ID.
Optimization GET – Use this method to retrieve the status of a submitted problem using the unique reference ID obtained from the POST method. If the optimization solution is ready, you can get the solution of the optimization problem.

Optimization POST Method #

POST: https://iq.ui.scheduledroutes.ddswireless.net

Use this method to submit your routing and scheduling optimization problem to the API. Once an optimization POST request is successfully submitted, the API will return a unique reference ID in the acknowledgement response. Use this unique ID to retrieve the actual solution using the Optimization GET Method (see next section).

An example for submitting an optimization problem using the POST method using a sample token and payload:

curl -X POST "https://iq.scheduledroutes.ddswireless.net/raas/optimization" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer fgJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJhZWU2MDQyZC0zN2E3LTQxNDYtODRlYy04YWU3M2ViODQ4YTgiLCJmaXJzdE5hbWUiOiJUZWMiLCJsYXN0TmFtZSI6IlRyYW5zaXQiLCJzZXF1ZW5jZU51bWJlciI6MSwicm9sZU5hbWVzIjpbImFkbWluIl0sInByb3ZpZGVyTmFtZXMiOlsiQUxMIl0sInVzZXJUZW5hbnRzIjpbMl0sInBlcm1pc3Npb25zIjpbMCwxNjYsMTcwLDE4MSwxODYsMTkxLDIwMCwxLDIsMyw0LDUsNiw3LDgsOSwxMCwxMSwxMiwxMywxNCwxNSwxNiwxNywxOCwxOSwyMCwyMSwyMiwyMywyNCwyNSwyNiwyNywyOCwxNTgsMTU5LDE2MywxNjgsMTgyLDE4OSwxNTcsMTE4LDExOSwxMjAsMTIxLDEyMiwxMjMsMTc1LDE3NiwxOTcsMTk1LDIwNSwyMDIsMjAzLDIwNiwyMTcsMjE5LDE5NiwyMDcsMTk0LDIxNCwyMTgsMjIwLDI5LDMwLDMxLDMyLDMzLDM0LDM1LDM2LDM3LDM4LDM5LDQwLDQxLDQyLDQzLDQ0LDQ1LDQ2LDQ3LDQ4LDQ5LDUwLDUxLDUyLDUzLDU0LDU1LDU2LDU3LDU4LDU5LDYwLDYxLDYzLDY0LDY1LDY2LDY3LDY4LDY5LDcwLDcxLDcyLDczLDc0LDc1LDc2LDc3LDgyLDgzLDg2LDg3LDg4LDg5LDkxLDkyLDkzLDk0LDk1LDk2LDEwMCwxMDEsMTAyLDEwMywxMDQsMTA1LDEwNiwxMDcsMTA4LDEwOSwxMTAsMTExLDExMiwxMTMsMTE0LDExNSwxMTYsMTE3LDEyNCwxMjUsMTI2LDEyNywxMjgsMTI5LDEzMCwxMzEsMTMyLDEzMywxMzQsMTM1LDEzNiwxMzcsMTM4LDEzOSwxNDAsMTQxLDE0MiwxNDMsMTQ0LDE0NSwxNDYsMTQ3LDE0OCwxNDksMTUwLDE1MSwxNTIsMTUzLDE1NCwxNTUsMTU2LDE2MiwxNjUsMTcxLDE4NCwxODcsMTkyLDE5OSwxNzMsMTk4LDE2MCwxNjEsMTY5LDE4MywxODgsODQsOTcsOTgsOTksMTY3LDE3MiwxODAsMTg1LDE5MCwxOTMsMTc0LDE2NCwyMDQsMjE1XSwicGFzc3dvcmRVcGRhdGVkQXQiOiIiLCJ0ZW5hbnQiOnsiaWQiOjIsIm5hbWUiOiJ0ZWNUcmFuc2l0Iiwic2l0ZUlkIjoiOTQiLCJ0aW1lem9uZSI6IkFtZXJpY2EvTG9zX0FuZ2VsZXMiLCJ0eXBlIjoiUmFhUyIsInNlc1VybCI6Imh0dHA6Ly9zdHJhdGVneS1lbmdpbmUtbXVsdGktdGVuYW50LTM6MTYwMDAiLCJkaXNwbGF5TmFtZSI6IlRlYyBUcmFuc2l0In0sInJvbGVzIjpbMjBdLCJpYXQiOjE3NDE5MDU2ODIsImV4cCI6MTc0NDQ5NzY4MiwiaXNzIjoiaXEuc2NoZWR1bGVkcm91dGVzLmRkc3dpcmVsZXNzLm5ldCJ9.fmdXyIylp604DCewvtuKCqLGhh-GFPfJNC9p2v4D-kHxhN2ZmRkHfknpTjiWZOZnB7AnWTUAh6BfZztNR_KLpQDPXcEpNL01lrw7ypIuwIf6CwA3Kwh916mNX-kgvPsyRQvAnvkyd-YO8M6zd_lsVD8oRnb-g07Vta3s3U-Y5uyWnQzv9PEeRf2IizflzlMkM7f1q472_3FQAEmomqMrSreK-YwUP9YxzD-QOW4GaaIUK5pgnzFYgEH2DFNU8KtDPeRdEk1cXL8aACFeawZnYzndvNcuv5fxd-9r-Y4-Tr8NiUwerdhRX3CuD5L5E6JVQdYOUJMFtSVpCbV7smaOJa" \
     -d @payload.json

In the above example, we assumed that the input problem is in a file called payload.json. You need to replace the sample token <strong>fgJhbGciOiJSUzI1N</strong>..... with your own token. The schema for the input problem is defined in the “Problem” section.

After submitting the POST method, you will get a response message with the following format:

Response Schema for the POST method:

{
 "id": "string",
 "message": "string",
 "status": "string",
 "error" : "string"
}

If the submission is successful, the status will be “202,” with the message reading “accepted” and the id representing the unique reference number for the asynchronous operation. This ID is used to track the status of the operation and retrieve results later. If there is an error, the status will indicate an error code, the id will be zero or empty, the message will be “failure” and the error will describe the error. For more details, please refer to the POST status codes below.

POST Example (Windows PowerShell):
The script below demonstrates how to make a POST request using a sample payload in Windows PowerShell. It assumes the input payload is stored in a file named payload.json, and the API access token is saved in token.txt. Upon execution, the generated ID is written to id.txt. To run PowerShell, simply type PowerShell in the start menu or command line.

$token = Get-Content token.txt -Raw
$headers = @{
    Authorization = "Bearer $token"
    "Content-Type" = "application/json"
}
$body = Get-Content payload.json -Raw
$response = Invoke-RestMethod -Uri "https://iq.scheduledroutes.ddswireless.net/raas/optimization" -Method Post -Headers $headers -Body $body
$response.id | Out-File -Encoding utf8 id.txt
Write-Output $response

POST Status Codes #

curl -X GET "https://iq.scheduledroutes.ddswireless.net/raas/optimization/ID" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer fgkhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJhZWU2MDQyZC0zN2E3LTQxNDYtODRlYy04YWU3M2ViODQ4YTgiLCJmaXJzdE5hbWUiOiJUZWMiLCJsYXN0TmFtZSI6IlRyYW5zaXQiLCJzZXF1ZW5jZU51bWJlciI6MSwicm9sZU5hbWVzIjpbImFkbWluIl0sInByb3ZpZGVyTmFtZXMiOlsiQUxMIl0sInVzZXJUZW5hbnRzIjpbMl0sInBlcm1pc3Npb25zIjpbMCwxNjYsMTcwLDE4MSwxODYsMTkxLDIwMCwxLDIsMyw0LDUsNiw3LDgsOSwxMCwxMSwxMiwxMywxNCwxNSwxNiwxNywxOCwxOSwyMCwyMSwyMiwyMywyNCwyNSwyNiwyNywyOCwxNTgsMTU5LDE2MywxNjgsMTgyLDE4OSwxNTcsMTE4LDExOSwxMjAsMTIxLDEyMiwxMjMsMTc1LDE3NiwxOTcsMTk1LDIwNSwyMDIsMjAzLDIwNiwyMTcsMjE5LDE5NiwyMDcsMTk0LDIxNCwyMTgsMjIwLDI5LDMwLDMxLDMyLDMzLDM0LDM1LDM2LDM3LDM4LDM5LDQwLDQxLDQyLDQzLDQ0LDQ1LDQ2LDQ3LDQ4LDQ5LDUwLDUxLDUyLDUzLDU0LDU1LDU2LDU3LDU4LDU5LDYwLDYxLDYzLDY0LDY1LDY2LDY3LDY4LDY5LDcwLDcxLDcyLDczLDc0LDc1LDc2LDc3LDgyLDgzLDg2LDg3LDg4LDg5LDkxLDkyLDkzLDk0LDk1LDk2LDEwMCwxMDEsMTAyLDEwMywxMDQsMTA1LDEwNiwxMDcsMTA4LDEwOSwxMTAsMTExLDExMiwxMTMsMTE0LDExNSwxMTYsMTE3LDEyNCwxMjUsMTI2LDEyNywxMjgsMTI5LDEzMCwxMzEsMTMyLDEzMywxMzQsMTM1LDEzNiwxMzcsMTM4LDEzOSwxNDAsMTQxLDE0MiwxNDMsMTQ0LDE0NSwxNDYsMTQ3LDE0OCwxNDksMTUwLDE1MSwxNTIsMTUzLDE1NCwxNTUsMTU2LDE2MiwxNjUsMTcxLDE4NCwxODcsMTkyLDE5OSwxNzMsMTk4LDE2MCwxNjEsMTY5LDE4MywxODgsODQsOTcsOTgsOTksMTY3LDE3MiwxODAsMTg1LDE5MCwxOTMsMTc0LDE2NCwyMDQsMjE1XSwicGFzc3dvcmRVcGRhdGVkQXQiOiIiLCJ0ZW5hbnQiOnsiaWQiOjIsIm5hbWUiOiJ0ZWNUcmFuc2l0Iiwic2l0ZUlkIjoiOTQiLCJ0aW1lem9uZSI6IkFtZXJpY2EvTG9zX0FuZ2VsZXMiLCJ0eXBlIjoiUmFhUyIsInNlc1VybCI6Imh0dHA6Ly9zdHJhdGVneS1lbmdpbmUtbXVsdGktdGVuYW50LTM6MTYwMDAiLCJkaXNwbGF5TmFtZSI6IlRlYyBUcmFuc2l0In0sInJvbGVzIjpbMjBdLCJpYXQiOjE3NDE5MDU2ODIsImV4cCI6MTc0NDQ5NzY4MiwiaXNzIjoiaXEuc2NoZWR1bGVkcm91dGVzLmRkc3dpcmVsZXNzLm5ldCJ9.fmdXyIylp604DCewvtuKCqLGhh-GFPfJNC9p2v4D-kHxhN2ZmRkHfknpTjiWZOZnB7AnWTUAh6BfZztNR_KLpQDPXcEpNL01lrw7ypIuwIf6CwA3Kwh916mNX-kgvPsyRQvAnvkyd-YO8M6zd_lsVD8oRnb-g07Vta3s3U-Y5uyWnQzv9PEeRf2IizflzlMkM7f1q472_3FQAEmomqMrSreK-YwUP9YxzD-QOW4GaaIUK5pgnzFYgEH2DFNU8KtDPeRdEk1cXL8aACFeawZnYzndvNcuv5fxd-9r-Y4-Tr8NiUwerdhRX3CuD5L5E6JVQdYOUJMFtSVpCbV7smaOJs"

curl -X GET "https://iq.scheduledroutes.ddswireless.net/raas/optimization/5" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer fgkhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJhZWU2MDQyZC0zN2E3LTQxNDYtODRlYy04YWU3M2ViODQ4YTgiLCJmaXJzdE5hbWUiOiJUZWMiLCJsYXN0TmFtZSI6IlRyYW5zaXQiLCJzZXF1ZW5jZU51bWJlciI6MSwicm9sZU5hbWVzIjpbImFkbWluIl0sInByb3ZpZGVyTmFtZXMiOlsiQUxMIl0sInVzZXJUZW5hbnRzIjpbMl0sInBlcm1pc3Npb25zIjpbMCwxNjYsMTcwLDE4MSwxODYsMTkxLDIwMCwxLDIsMyw0LDUsNiw3LDgsOSwxMCwxMSwxMiwxMywxNCwxNSwxNiwxNywxOCwxOSwyMCwyMSwyMiwyMywyNCwyNSwyNiwyNywyOCwxNTgsMTU5LDE2MywxNjgsMTgyLDE4OSwxNTcsMTE4LDExOSwxMjAsMTIxLDEyMiwxMjMsMTc1LDE3NiwxOTcsMTk1LDIwNSwyMDIsMjAzLDIwNiwyMTcsMjE5LDE5NiwyMDcsMTk0LDIxNCwyMTgsMjIwLDI5LDMwLDMxLDMyLDMzLDM0LDM1LDM2LDM3LDM4LDM5LDQwLDQxLDQyLDQzLDQ0LDQ1LDQ2LDQ3LDQ4LDQ5LDUwLDUxLDUyLDUzLDU0LDU1LDU2LDU3LDU4LDU5LDYwLDYxLDYzLDY0LDY1LDY2LDY3LDY4LDY5LDcwLDcxLDcyLDczLDc0LDc1LDc2LDc3LDgyLDgzLDg2LDg3LDg4LDg5LDkxLDkyLDkzLDk0LDk1LDk2LDEwMCwxMDEsMTAyLDEwMywxMDQsMTA1LDEwNiwxMDcsMTA4LDEwOSwxMTAsMTExLDExMiwxMTMsMTE0LDExNSwxMTYsMTE3LDEyNCwxMjUsMTI2LDEyNywxMjgsMTI5LDEzMCwxMzEsMTMyLDEzMywxMzQsMTM1LDEzNiwxMzcsMTM4LDEzOSwxNDAsMTQxLDE0MiwxNDMsMTQ0LDE0NSwxNDYsMTQ3LDE0OCwxNDksMTUwLDE1MSwxNTIsMTUzLDE1NCwxNTUsMTU2LDE2MiwxNjUsMTcxLDE4NCwxODcsMTkyLDE5OSwxNzMsMTk4LDE2MCwxNjEsMTY5LDE4MywxODgsODQsOTcsOTgsOTksMTY3LDE3MiwxODAsMTg1LDE5MCwxOTMsMTc0LDE2NCwyMDQsMjE1XSwicGFzc3dvcmRVcGRhdGVkQXQiOiIiLCJ0ZW5hbnQiOnsiaWQiOjIsIm5hbWUiOiJ0ZWNUcmFuc2l0Iiwic2l0ZUlkIjoiOTQiLCJ0aW1lem9uZSI6IkFtZXJpY2EvTG9zX0FuZ2VsZXMiLCJ0eXBlIjoiUmFhUyIsInNlc1VybCI6Imh0dHA6Ly9zdHJhdGVneS1lbmdpbmUtbXVsdGktdGVuYW50LTM6MTYwMDAiLCJkaXNwbGF5TmFtZSI6IlRlYyBUcmFuc2l0In0sInJvbGVzIjpbMjBdLCJpYXQiOjE3NDE5MDU2ODIsImV4cCI6MTc0NDQ5NzY4MiwiaXNzIjoiaXEuc2NoZWR1bGVkcm91dGVzLmRkc3dpcmVsZXNzLm5ldCJ9.fmdXyIylp604DCewvtuKCqLGhh-GFPfJNC9p2v4D-kHxhN2ZmRkHfknpTjiWZOZnB7AnWTUAh6BfZztNR_KLpQDPXcEpNL01lrw7ypIuwIf6CwA3Kwh916mNX-kgvPsyRQvAnvkyd-YO8M6zd_lsVD8oRnb-g07Vta3s3U-Y5uyWnQzv9PEeRf2IizflzlMkM7f1q472_3FQAEmomqMrSreK-YwUP9YxzD-QOW4GaaIUK5pgnzFYgEH2DFNU8KtDPeRdEk1cXL8aACFeawZnYzndvNcuv5fxd-9r-Y4-Tr8NiUwerdhRX3CuD5L5E6JVQdYOUJMFtSVpCbV7smaOJs"

 {
  status: "string",
  message: "string",
  error: "string",
 "solution": {
      "statistics": {},
      "routes": []
      "unassigned": [],
      }  
}

$token = Get-Content token.txt -Raw
$id = Get-Content id.txt -Raw
$headers = @{
    Authorization = "Bearer $token"
    "Content-Type" = "application/json"
}

$url = "https://iq.scheduledroutes.ddswireless.net/raas/optimization/$id"

$response = Invoke-RestMethod -Uri $url -Method Get -Headers $headers
$response | ConvertTo-Json -Depth 10 | Out-File -Encoding utf8 response.txt

We will now provide a detailed description of each of these components:

fleet: [required] it specifies a list of vehicles along with their associated information, such as shift schedules, start and end locations, breaks, capacities, and skills.

For each vehicle, you can define one or multiple shift schedules by specifying the start and end times, as well as the corresponding locations. To identify these locations, you’ll need to provide their Geo-coordinates, which consist of latitude and longitude.
Each vehicle may have one or more breaks. For each break, you can define a time window during which it can be taken, as well as the location and duration of the break.
For each vehicle, you can define one or more capacity types along with the available units for each type. Vehicle capacity can be represented using multidimensional units of measure, such as volume, mass, or size.
For each vehicle, you can specify one or more skills that enable it to perform certain jobs. For example, you might assign “welding machine” and “oxygen tank” as skills for one vehicle, and “lift” as a skill for another vehicle. If a job requires a lift, only the vehicle equipped with this skill will be able to serve it. You can also set limits for each vehicle, such as the maximum number of stops and the maximum travel distance (in miles).

jobs: [required] it specifies a list of jobs to be served by the vehicles specified in the fleet object. Each job can include a series of tasks, which may be only pickups, only deliveries, or a both pickups and deliveries. For “visit” jobs where we need to visit a location to perform a job (e.g. repairs, installing modem, etc.), you can consider them as a delivery task with or without a capacity demand. For each task, you can define various attributes such as their location, time windows, duration, capacity requirements, and necessary skills.

To specify the location of a task, you need to provide its Geo-coordinate, which includes latitude and longitude.
If you set a service time window for a task, the optimizer will schedule the task to occur within that time frame. In other words, the estimated time of arrival (ETA) for the task in the API response will fall within the specified time window. If the optimizer cannot find a suitable ETA for a task within its specified time window, the task will remain unassigned. For tasks that are flexible or not time-sensitive, you can specify a broader time window, with a maximum span of 24 hours. The API uses the ISO timestamps as described earlier.
You can specify a duration (in seconds) for each task. This is the time spent at a given location either for loading or unloading an item or performing the task.
You can specify the capacity requirements for each task using multidimensional units of measure, such as volume, mass, or size. Additionally, you can create custom names for your capacity types, such as “seat,” “container,” “pallet,” or “bin.” For each capacity type, you can also define the exact amount needed to perform the task.
You can also define a list of required skills for each task. Only vehicles with a matching skill set will be eligible to perform that task. For example, if you specify “welding machine” and “oxygen tank” as the required skills for a task, only vehicles equipped with these skills will be selected to complete the task.

objective: [optional] it determines the optimization objective or strategy. Currently, the following three objectives are supported by the API:

Minimize Total Travel Time: This is the default optimization strategy, and it tries to minimize the total travel time of the fleet while completing the specified jobs.
Minimize Number of Routes: This optimization strategy focuses on reducing the number of vehicles needed to complete the specified jobs. However, this may lead to increased total travel time for the fleet or greater workload on individual vehicles as a trade-off.
Balance Workload among Routes: This optimization strategy aims to evenly distribute the workload among all vehicles in the fleet. However, this balance may result in increased total travel time for the fleet.

configuration: [optional] through configuration, you can adjust API settings or modify default options. For example, you can specify whether to include a summary of optimization statistics (such as total travel time and distance) or a list of unassigned tasks in the API response.

Input Request Schema: #

The schema of the input request to solve a route optimization problem is as follows:

 "problem": {
      "fleet": required 
        [
          "shifts": [optional]
          "capacities": [required]
          "limits": {optional}
          "skills" : [optional]
          "id": required
          "routeTemplateId" : optional
          "maxInstances": optional   
        ],
      "jobs": required
        [
          "pickups": [...] 
          "deliveries": [...]
          "id" : required
        ]
      "objective": optional
      "configuration": {optional}
      "version": optional
    }

To submit a problem using the API, this request must be included in the POST method as described in the “Get Started” section.

In a route optimization problem, a fleet of vehicles aims to serve a set of jobs efficiently. The above schema allows users to define their fleet and their jobs. In the current version of the API, each job can be:

1. Pickup tasks only: These tasks involve picking up items along the route and delivering them to the route’s end location.

2. Delivery tasks only: These tasks require delivering items that are loaded onto the vehicle at the beginning of the route.

3. Pickup and delivery (P/D) tasks together: These tasks combine both pickup and delivery actions. They involve picking up something at one location and bringing it to another location.

Additionally:

1. If only the “pickups” object is provided for a job, it’s considered a pickup-only job.

2. If only the “deliveries” object is provided for a job, it’s considered a delivery-only job.

3. When both “pickups” and “deliveries” are provided for a job, it’s categorized as a pickup and delivery job.

For each task, various attributes and constraints can be defined, such as capacity demands, service time windows, and required skills. Visit tasks, where we need to visit specific locations to perform tasks (e.g. repairs), can indeed be seen as a specialized form of delivery tasks (with or without capacity requirements). Tasks are assigned to vehicles whose capacities or skill sets match the task’s requirements. For example, if a task requires a lift or ladder, only vehicles equipped with a lift or ladder will be used to perform that task.

Now, let’s delve into the details of each element in the input API payload.

problem [required]: it specifies the routing and scheduling optimization problem you would like to solve. It consists of the following attributes:

fleet [required]: it defines the fleet information. It is an array of fleet objects. Each fleet object consists of the following attributes:

id: [required] a unique identifier (integer) for the vehicle.
shifts: [optional] an array of shift objects, each shift object contains the data for the shift start and end locations and times as well as an array of breaks objects each containing the break start and end locations and times. Multiple shift objects can be defined but they must be disjoint. Elements in each shift object:

start: the shift start time and start location

time: [optional]. It specifies the shift start time. If it is not specified, it will default to 00:00:00 (midnight) of the current date.
location: [optional]. It specifies the Geo-coordinate (latitude and longitude) of the start location. You can specify it as an array such as [A,B] in which A represents the latitude and B represents the longitude. Alternatively, you can specify it as {"lat": A,"lng": B}.

end: the shift end time and end location

time: [optional]. It specifies the shift end time. If it is not specified, it will default to 23:59:00 of the current date.
location: [optional]. It specifies the Geo-coordinate (latitude and longitude) of the end location. You can specify it as an array such as [A,B] in which A represents the latitude and B represents the longitude. Alternatively, you can specify it as {"lat": A,"lng": B}.

breaks: [optional] an array of break objects

serviceWindow: [required if breaks is used]: the time period in which the break can happen
duration: [required if breaks is used]: an integer defining the duration of the break in seconds
location: [optional]: the location of the break. You can specify it as an array such as [A,B] in which A represents the latitude and B represents the longitude. Alternatively, you can specify it as {"lat": A,"lng": B}.location is optional. If the location is omitted the break is ‘floating’ which means that it can be taken anywhere at the convenience of the driver.

"shifts": [{
  "start": {
    "time": "2020-07-04T09:00:00-08:00",
    "location": {"lat": 52.46642, "lng": 13.28124}
  },
  "end": {
    "time": "2020-07-04T18:00:00-08:00",
    "location": [54.21981, 14.01237]
  },
  "breaks": [
    {
      "serviceWindow": ["2020-07-04T12:00:05-08:00","2020-07-04T14:05:05-08:00"],
      "duration": 1200,
      "location": {"lat": 53.70645, "lng": 12.34156}
    },
    {
      "serviceWindow": ["2020-07-04T16:00:00-08:00","2020-07-04T16:45:00-08:00"],
      "duration": 600,
      "location": {"lat": 51.46642, "lng": 12.28124}
    }
    ]
  }]

capacities: [required] an array of capacity objects. Each capacity object is a key-value object defined with the following keys:

name: [required] a string specifying the name of the capacity type (e.g. “wheelchair”, “box”,” seat”, “bin”)
units: [required] an integer number specifying the available units of the capacity type

For example, if a vehicle has a capacity for 2 seats and 20 packages, you can define its capacity as follows:

    "capacities": [
        {
        "name": "seat",
        "units": 2,
        },
        {
        "name": "package",
        "units": 20,
        }        
      ]

skills: [optional] a list of vehicle skills or equipment, each represented by an arbitrary string specific to your application. This allows you to customize the capabilities of your vehicles to match the requirements of the jobs they need to serve. Example:

"skills": ["lift","fridge","oxygen tank"]

limits: [optional] specifies constraints applied to the vehicle

maxDistance: [optional] an integer number specifying the maximum distance limitation for the vehicle in miles
maxStops: [optional] an integer defining maximum number of stops (pickup or delivery tasks) the vehicle can serve in one shift
lifoDepth: [optional] an integer defining the LIFO (Last In First Out) depth of the vehicle

  "limits": {
    "lifoDepth" : 1,
    "maxDistance": 3000,
    "maxStops" : 20,
  }

lastKnownLocation: [optional, used for re-optimization only] Specifies the last known location of the vehicle at the specified time. This information is crucial for re-optimizing an ongoing route to account for new changes, such as broken vehicles, late jobs, new jobs, or canceled jobs. The API uses this data to re-optimize the plan efficiently. Therefore, when re-optimizing an existing schedule, you need to provide the location of all involved vehicles.

Example:

"lastKnownLocation": {
      "location": {"lat":53.45612, "lng":12.65421},
      "time" : "2020-07-04T12:00:05-08:00"
      }

routeTemplateId: [optional] It is a unique identifier used to define a route template. The API supports the concept of ‘Route Templates,’ which allow you to define the specifications for a particular vehicle type and request the API to generate a specific number of such vehicles for routing and scheduling optimization. A route template contains the same information as a route or vehicle but you can specify a “size” parameter called maxInstances for it. For instance, suppose you have 100 vehicles. You might define 2 or 3 route templates:

1. Shift 6am-6pm, capacity 4, size=60
2. Shift 1pm-1am, capacity 4, size= 50
3. Shift 6am-8pm, capacity 10, size=35

maxInstances: [optional] If routeTemplateId is provided, maxInstances specifies how many route templates should be generated based on the specified route template.

jobs: an array of job objects [at least one job is required]:

id: [required] a unique identifier (integer) for the job
pickups: [optional] an array of Task Objects, each defining a pickup task
deliveries: [optional] an array of Task Objects, each defining a delivery (or drop-off) task

• The API does not support jobs with multiple pickups and multiple deliveries.
• The API does not support jobs with no pickups and no deliveries.
• If only "pickups" is specified, the job is classified as a pickup-anchored job.
• If only "deliveries" is specified, the job is classified as a delivery-anchored job.
• If a job has both a pickup and a delivery, the anchor is determined by the task that defines a service window.
• If both tasks have service windows, the job is treated as a pickup-anchored job.

Each Task Object consists of the following attributes:

id: [required] a unique identifier (integer) for the task
location: [required] It is a key-value object that specifies the Geo-coordinates (latitude and longitude) of the location where the task must be performed. You can specify it as an array such as [A,B] in which A represents the latitude and B represents the longitude. Alternatively, you can specify it as {"lat": A,"lng": B}.

Example:

"location": {"lat": 52.46642, "lng": 13.28124}
"location": [52.46642, 13.28124]

serviceWindows: [optional or required depending on the use case, see the definition of pickups and deliveries above] It specifies the service time window for performing the task. The service window is an array with this format: [A, B] where A and B are the start and end times of the service time window. The API will attempt to produce an ETA within the specified service window for that task. If this is not possible, the task will be listed as unassigned. In other words, times “A” and “B” define the earliest and latest times by which a task must be completed by a vehicle. For tasks that are flexible or not time-sensitive, use an arbitrarily large window (max 24 hours) to give the API more flexibility in scheduling other tasks. The current version of the API supports only one service window for each task.

For pickups only and deliveries only tasks, the service window is required. Example:

"serviceWindows": ["2024-08-30T09:00:00-08:00",
                   "2024-08-30T21:00:00-08:00"]

duration: [required] It specifies the duration of the task in seconds. It can be either an integer or a key-value object with the following keys:

"fixed": the fixed duration (seconds) for the job (e.g. for finding parking, lowering the lift, etc.)
"service": the service duration (seconds) for doing the job.

Examples:

"duration": 1950
   OR
"duration": {"fixed":150, "service": 1800}

demand: [optional] an array of capacity demands for the task. The structure of each demand object is identical to that of the capacity object in the fleet entity defined above. Each capacity item consists of a name (string) and its available units (integer). The specified names must match those defined in the capacity object of the fleet entity. For example, if a job requires capacity for two seats and 20 packages, you will define the demand as follows:

"demand": [
    {
    "name": "seat",
    "units": 2,
    },
    {
    "name": "package",
    "units": 20,
    }        
  ]

skills: [optional] an array of skills or equipment required to perform the task, each represented by an arbitrary string specific to your application. Only vehicles whose skills set match the skill set of the task will be considered for performing the task. These skills are matched to the skills defined in the fleet entity defined above. Example:

"skills": ["lift", "ladder", "welding machine"]

status: [optional, used for re-optimization only] it is a string that specifies the status of the task which can be one of these options: "pending", "in_progress", "performed". This information is crucial for re-optimizing an ongoing route to account for new changes, such as broken vehicles, late jobs, new jobs, or canceled jobs. The API uses this data to re-optimize the plan efficiently. Therefore, when re-optimizing an existing schedule, you need to specify the value of this attribute. For new tasks or tasks that are not performed yet, set it to "pending". If the task is already performed set it to "performed". If the vehicle has already arrived at the location to do the task, and the task is in progress, set it to "in_progress". The default value is "pending".

Example: "status": "pending"

vehicleId: [optional, used for re-optimization only], it specifies the assigned vehicle ID (integer) for the already-scheduled tasks. This information is crucial for re-optimizing an ongoing route to account for new changes, such as broken vehicles, late jobs, new jobs, or canceled jobs. The API uses this data to re-optimize the plan efficiently. Therefore, when re-optimizing an existing schedule, you need to specify the value of this attribute. The default value is zero. For new tasks, set it to zero. For existing tasks that are already assigned to a vehicle, set this attribute to the assigned vehicle ID.

Example: "vehicleId": 12

eta: [optional, used for re-optimization only], it specifies the current ETA (estimated time of arrival) for the already-scheduled jobs. This information is crucial for re-optimizing an ongoing route to account for new changes, such as broken vehicles, late jobs, new jobs, or canceled jobs. The API uses this data to re-optimize the plan efficiently. Therefore, when re-optimizing an existing schedule, you need to specify the value of this attribute. The default value is 0. For the new or performed tasks, set it to 0 but for the existing pending tasks, set it to the existing ETA.

Example: "eta": "2021-07-04T12:13:00-08:00"

objective: [optional] an integer specifying the optimization objective (strategy): (default = 1)

1: Minimize Total Travel Time [default]

2: Minimize Number of Routes

3: Balance Workload Among Routes

Example: "objective": 1

configuration: [optional] it can be used to specify some additional settings or configurations:

polylineType: [optional] it specifies the type of the output polyline that can be returned for each scheduled route. It is a string from these options: "none", "plain", "encoded". If "none"is selected, no polylines will be included in the output API response. If "plain" is specified, an ordered list of intersections that we need to travel between each pair of consecutive stops will be returned as the polyline. If "encoded" is used, the polyline is compressed into a string format that users can provide to third-party navigation APIs, such as Google Maps, to obtain turn-by-turn instructions. The default value is "none".

unassignedTasks: [optional] it is a flag that determines whether the unassigned tasks must be included in the output response or not. Default is False. If, for any reason, the API cannot assign a task to a route, it will list it as unassigned.

statistics: [optional] it is a flag that determines whether the optimization statistics must be included in the output solution or not. Default is True.

units: [optional] it specifies the units for the output statistics as well as the units for the fleet limits. It can be either "metric" or "imperial". The default value is "metric".

maxRideTable: [optional] it defines the maximum onboard time for all jobs. It is defined by a static table in which each row is an array containing three time values (in minutes): [A, B, C]. This means if the direct travel time for a job is between A and B, the maximum onboard time is equal to “rideTime+C”. For example, here’s a simple table with two rows: "maxRideTable":[[0, 10, 30], [11, 20, 40]]. Default is [[0, 300, 720]]. Overlap and gaps are not allowed in this table. Also, the granularity is minutes.

vechicleCapacities: [optional] vehicle capacity definitions can be named and then used in the fleet section. This is particularly useful for complex definitions when a vehicle can have many configurations. For example if a vehicle can fit either (10 ‘ambulatory’ and 0 ‘wheelchair’ passengers) OR (8 ‘ambulatory’ and 1 ‘wheelchair’ passengers) you could define "vehicleCapacities":{"flexBus": [[{"name": "ambulatory", "units": 10}], [{"name": "ambulatory", "units": 8},{"name":"wheelchair", "units": 1}]]}. And then in the fleet property you can use fleet[<index>].capacities: "flexBus" for each flexBus in the fleet. Named vehicle capacities can also be saved in your personal customer profile where they become available for use without having to define them in the configuration section. If a named vehicle capacity is present in both your personal profile and the payload, the definition in the payload has precedence.

freezeWindowLength: [optional] The freeze window length in minutes. A freeze window is a concept that only applies to same-day optimization and is useful when re-optimizing a problem. For example if you have already optimized a problem but want to make changes in the middle of the day, you could re-send the problem (with appropriate task.status to reflect what has already been done) and set a freeze window of 60 minutes. This will instruct the optimizer that the time period extending 60 minutes from ‘now’ is off-limit. No tasks can be added/removed from any route within the freeze window.

lifoConstrainedCapacities: [optional] An array of capacity types that are subject to the LIFO (Last In, First Out) constraint. Example: "lifoConstrainedCapacities": ['wheelchair', 'scooter']

Example:

"configuration": 
{
      "polylineType": "plain",
      "unassignedTasks": False,
      "statistics": True,
}

version: [optional]: it specifies the version of the API. Default is 1.0.

Solution #

As explained in the “Get Started” section, once you submit a problem via the POST method, you will receive a unique reference ID. You can use this reference ID with the GET method to retrieve the status of the submitted problem. If the optimization solution is ready, you can access it in the "solution" entity of the received response. As shown in the following figure, the "solution" entity is composed of three main parts:

"statistics": it includes various statistics (metrics) that provide an overview of the entire solution across all routes, allowing you to evaluate its effectiveness. These metrics include, for example, the total travel distance for all optimized routes. By analyzing these statistics, you can measure the quality and efficiency of the produced solution. These insights help in understanding the performance and impact of the optimization process.

"routes": it contains the optimized routes along with their stops and their estimated time of arrival (ETA). It can also include the polyline of each route.

"unassigned": it contains the list of unassigned tasks. If the API cannot assign a task to a route during the optimization process, it will be listed as unassigned. Additionally, it can include reasons for why each task remains unassigned, providing insights into potential constraints or issues that prevented their assignment.

Output Solution Schema: #

The template of the solution of the optimization problem provided in the output response of the API is as follows:

 "solution": {
      "statistics": {},
      "routes": []
      "unassigned": [],
      }  

The "solution" entity represents the solution of the route optimization problem which consists of the following attributes:

statistics: it contains the statistics of the entire solution and consists of the following properties:

“distance”:

“totalDistance” : the total distance traveled by the entire fleet. This measurement includes the distance from each vehicle’s start location to its end location.

“revenueDistance“: the total revenue distance traveled by the entire fleet. This measurement includes the distance from the first stop to the last stop for each vehicle. It does not include the distance from the vehicle’s start location to the first stop or the distance from the last stop to the vehicle’s end location.

“vehicles”:

“used”: The number of used vehicles in the solution to perform the scheduled jobs/tasks.

“unused”: The number of unused vehicles

“jobs”:

“scheduledTasks”: The number of scheduled tasks

“unassignedTasks”: The number of unassigned tasks

“times”:

“totalHours”: the total travel hours for the entire fleet. This measurement includes the time spent traveling from each vehicle’s start location to its end location.

“revenueHours“: the total revenue hours traveled by the entire fleet. This measurement includes the time taken from the first stop to the last stop for each vehicle. It does not include the time spent traveling from the vehicle’s start location to the first stop or from the last stop to the vehicle’s end location.

Example:

"statistics": {
    "distance": {
        "totalDistance": 42,
        "revenueDistance": 25
    },
    "vehicles": {
        "used": 2,
        "unused": 0
    },
    "jobs": {
        "scheduledTasks": 3,
        "unassignedTasks": 0
    },
    "times": {
        "totalHours": 11.6,
        "revenueHours": 10.8
    }
}

routes: it provides an array of the scheduled route for each vehicle. Each scheduled route contains the following data:

“vehicleId”: an integer that specifies the ID of the assigned vehicle

“shifts”: an array of shift objects. Note that the API supports multiple shifts for each vehicle. Each shift object consists of the following elements:

“index”: the index of the shift (integer)

“stops”: it provides an array of all stops to be performed by the vehicle on this shift. Each stop has the following properties:

“ordinal”: The stop’s position within the vehicle schedule, represented by its index (integer).

“jobId”: The job ID related to this stop (integer)

“taskId”: The task ID related to this stop (integer)

“type”: The type (string) of the task that must be performed at this stop (“pickup” or “delivery”)

“location”: The Geo-coordinates of the location of the stop

“eta”: The estimated time of arrival (ETA) for the stop (in the same time zone of the input payload)

“timeToNext”: This is the driving time to the next stop. For example, if you drop-off a passenger at 9:00am and your next job is at 10:00, this stat tells you that the driving time from the current stop to the next stop is 20mins.

“distanceToNext”: This is the driving distance to the next stop. Depending on the chosen units in the “configuration”, this can represent miles or meters.

“waitTime”: the wait time tells you how long the driver should wait at the next stop if he starts driving now.

“polyline”: The polyline connecting the stop to its preceding stop. If “plain” polyline is specified in the “configuration”, the polyline is an ordered list of intersections that we need to travel between the preceding stop and the current stop. If “encoded” polyline is specified in the “configuration”, the plain polyline is encoded and returned as an encoded string.

“break”: if the scheduled stop is for a break, it represents the ID of the break. Other stops don’t have this element. The API does not enforce that the breaks (or jobs) be listed in chronological order.

Example:

       "routes": [
            {
                "vehicleId": 1,
                "shifts": [
                    {
                        "index": 1,
                        "stops": [
                            {
                                "break": 1,
                                "start": "2023-10-01T10:00:00-08:00",
                                "end": "2023-10-01T10:15:00-08:00",
                                "timeToNext": 15,
                                "distanceToNext": 7.3,
                                "waitTime": 0,
                                "polyline": null,
                                "ordinal": 1
                            },
                            {
                                "jobId": 4,
                                "taskId": 5,
                                "type": "pickup",
                                "location": [
                                    50.70816,
                                    -120.37796
                                ],
                                "eta": "2023-10-01T10:30:00-08:00",
                                "timeToNext": 13,
                                "distanceToNext": 5.6,
                                "waitTime": 112,
                                "polyline": null,
                                "ordinal": 2
                            },
                            {
                                "jobId": 4,
                                "taskId": 6,
                                "type": "delivery",
                                "location": [
                                    50.66559,
                                    -120.36924
                                ],
                                "eta": "2023-10-01T12:45:00-08:00",
                                "timeToNext": 4,
                                "distanceToNext": 1.7,
                                "waitTime": 71,
                                "polyline": null,
                                "ordinal": 3
                            },
                            {
                                "break": 2,
                                "start": "2023-10-01T14:00:00-08:00",
                                "end": "2023-10-01T14:15:00-08:00",
                                "timeToNext": 7,
                                "distanceToNext": 3.2,
                                "waitTime": 217,
                                "polyline": null,
                                "ordinal": 4
                            }
                        ]
                    }
                ]
            },
            {
                "vehicleId": 2,
                "shifts": [
                    {
                        "index": 1,
                        "stops": [
                            {
                                "break": 1,
                                "start": "2023-10-01T11:00:00-08:00",
                                "end": "2023-10-01T11:15:00-08:00",
                                "timeToNext": 3,
                                "distanceToNext": 1.2,
                                "waitTime": 267,
                                "polyline": null,
                                "ordinal": 1
                            },
                            {
                                "jobId": 10,
                                "taskId": 11,
                                "type": "pickup",
                                "location": [
                                    50.65187,
                                    -120.40052
                                ],
                                "eta": "2023-10-01T15:45:00-08:00",
                                "timeToNext": 12,
                                "distanceToNext": 6.4,
                                "waitTime": 0,
                                "polyline": null,
                                "ordinal": 2
                            },
                            {
                                "jobId": 10,
                                "taskId": 12,
                                "type": "delivery",
                                "location": [
                                    50.69262,
                                    -120.35412
                                ],
                                "eta": "2023-10-01T16:22:00-08:00",
                                "timeToNext": 6,
                                "distanceToNext": 2.7,
                                "waitTime": 91,
                                "polyline": null,
                                "ordinal": 3
                            }
                        ]
                    }
                ]
            }
        ]

unassigned: The optional unassigned task list is populated with tasks which cannot be assigned due to specific constraints. Each item consists of a job id, a task id, and possible unassignment reasons (a code plus a description):

“id”:

“job”: the job ID (integer) of the unassigned task

“task”: the ID (integer) of the unassigned task

“reason”: an array of possible reasons for the unassigned tasks

“code”: the code (integer) of the possible reason

“description”: the description (string) of the possible reason

{
  "unassigned": [
    {
      "id": {
        "job": 2,
        "task": 1
      },
      "reason": [
        {
          "code": 2,
          "description": "Not enough capacity for this job"
        }
      ]
    },
    {
      "id": {
        "job": "31",
        "task": "2"
      },
      "reason": [
        {
          "code": 5,
          "description": "The service time of the job is out of the shift hours"
        }
      ]
    }
  ]
}

Glossary #

Tutorials #

On this page, you’ll find various examples demonstrating how to use the API for various scenarios. The API primarily supports two main use cases:

1. Planning and Scheduling: Generates an optimized schedule for a fleet’s tours, considering constraints related to jobs and vehicles.

2. Re-optimization: Modifies an existing or ongoing schedule to reflect changes such as new jobs or cancellations as well as broken vehicles.

Explore the examples provided to see how these use cases are implemented:

Example 1: Planning a simple pickup and delivery (drop-off) scenario

Example 2: A simple re-optimization scenario for adding new jobs to an existing schedule

Example 3: Re-optimization with cancelled jobs

Example 4: Re-optimization with broken vehicles

{
    "problem": {
        "fleet": [
            {
                "id": 1,
                "shifts": [
                    {
                        "start": {
                            "time": "2023-10-01T08:00:00-08:00",
                            "location": {
                                "lat": 50.67293,
                                "lng": -120.34195
                            }
                        },
                        "end": {
                            "time": "2023-10-01T18:00:00-08:00",
                            "location": {
                                "lat": 50.67293,
                                "lng": -120.34195
                            }
                        },
                        "breaks": [
                            {
                                "serviceWindow": [
                                    "2023-10-01T10:00:00-08:00",
                                    "2023-10-01T10:30:00-08:00"
                                ],
                                "duration": 900,
                                "location": {
                                    "lat": 50.6531,
                                    "lng": -120.38393
                                }
                            },
                            {
                                "serviceWindow": [
                                    "2023-10-01T14:00:00-08:00",
                                    "2023-10-01T14:30:00-08:00"
                                ],
                                "duration": 900,
                                "location": {
                                    "lat": 50.6531,
                                    "lng": -120.38393
                                }
                            }
                        ]
                    }
                ],
                "capacities": [
                    {
                        "name": "seat",
                        "units": 15
                    },
                    {
                        "name": "cargo",
                        "units": 5
                    }
                ],
                "skills": [
                    "lift",
                    "air_conditioner"
                ]
            },
            {
                "id": 2,
                "shifts": [
                    {
                        "start": {
                            "time": "2023-10-01T08:00:00-08:00",
                            "location": {
                                "lat": 50.7117,
                                "lng": -120.39286
                            }
                        },
                        "end": {
                            "time": "2023-10-01T18:00:00-08:00",
                            "location": {
                                "lat": 50.67698,
                                "lng": -120.32012
                            }
                        },
                        "breaks": [
                            {
                                "serviceWindow": [
                                    "2023-10-01T11:00:00-08:00",
                                    "2023-10-01T11:30:00-08:00"
                                ],
                                "duration": 900,
                                "location": {
                                    "lat": 50.6531,
                                    "lng": -120.38393
                                }
                            }
                        ]
                    }
                ],
                "capacities": [
                    {
                        "name": "seat",
                        "units": 10
                    },
                    {
                        "name": "cargo",
                        "units": 8
                    }
                ],
                "skills": [
                    "lift"
                ]
            }
        ],
        "jobs": [
            {
                "id": 1,
                "pickups": [
                    {
                        "id": 2,
                        "location": [
                            50.65391,
                            -120.37365
                        ],
                        "serviceWindows": [
                            [
                                "2023-10-01T09:00:00-08:00",
                                "2023-10-01T09:30:00-08:00"
                            ]
                        ],
                        "duration": 600,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 2
                            }
                        ],
                        "skills": [
                            "lift"
                        ]
                    }
                ],
                "deliveries": [
                    {
                        "id": 3,
                        "location": [
                            50.69409,
                            -120.35425
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 2
                            }
                        ],
                        "skills": [
                            "lift"
                        ]
                    }
                ]
            },
            {
                "id": 4,
                "pickups": [
                    {
                        "id": 5,
                        "location": [
                            50.70816,
                            -120.37796
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            }
                        ],
                        "skills": [
                            "lift",
                            "air_conditioner"
                        ]
                    }
                ],
                "deliveries": [
                    {
                        "id": 6,
                        "location": [
                            50.66559,
                            -120.36924
                        ],
                        "serviceWindows": [
                            [
                                "2023-10-01T12:45:00-08:00",
                                "2023-10-01T13:30:00-08:00"
                            ]
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            }
                        ],
                        "skills": [
                            "lift",
                            "air_conditioner"
                        ]
                    }
                ]
            },
            {
                "id": 7,
                "pickups": [
                    {
                        "id": 8,
                        "location": [
                            50.70393,
                            -120.37263
                        ],
                        "serviceWindows": [
                            [
                                "2023-10-01T14:00:00-08:00",
                                "2023-10-01T14:30:00-08:00"
                            ]
                        ],
                        "duration": 600,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 3
                            }
                        ]
                    }
                ],
                "deliveries": [
                    {
                        "id": 9,
                        "location": [
                            50.69028,
                            -120.39028
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 3
                            }
                        ]
                    }
                ]
            }
        ],
        "objective": 1,
        "configuration": {
            "polylineType": "none",
            "unassignedTasks": true,
            "units": "imperial",
            "statistics": true
        }
    }
}

{
    "id": 8193,
    "status": 200,
    "solution": {
        "statistics": {
            "distance": {
                "totalDistance": 54,
                "revenueDistance": 36
            },
            "vehicles": {
                "used": 2,
                "unused": 0
            },
            "jobs": {
                "scheduledTasks": 3,
                "unassignedTasks": 0
            },
            "times": {
                "totalHours": 9.4,
                "revenueHours": 8.7
            }
        },
        "routes": [
            {
                "vehicleId": 1,
                "shifts": [
                    {
                        "index": 1,
                        "stops": [
                            {
                                "jobId": 1,
                                "taskId": 2,
                                "type": "pickup",
                                "location": [
                                    50.65391,
                                    -120.37365
                                ],
                                "eta": "2023-10-01T09:00:00-08:00",
                                "timeToNext": 10,
                                "distanceToNext": 4.9,
                                "waitTime": 0,
                                "polyline": null,
                                "ordinal": 1
                            },
                            {
                                "jobId": 1,
                                "taskId": 3,
                                "type": "delivery",
                                "location": [
                                    50.69409,
                                    -120.35425
                                ],
                                "eta": "2023-10-01T09:25:00-08:00",
                                "timeToNext": 10,
                                "distanceToNext": 5.4,
                                "waitTime": 25,
                                "polyline": null,
                                "ordinal": 2
                            },
                            {
                                "break": 1,
                                "start": "2023-10-01T10:00:00-08:00",
                                "end": "2023-10-01T10:15:00-08:00",
                                "timeToNext": 15,
                                "distanceToNext": 7.3,
                                "waitTime": 0,
                                "polyline": null,
                                "ordinal": 3
                            },
                            {
                                "jobId": 4,
                                "taskId": 5,
                                "type": "pickup",
                                "location": [
                                    50.70816,
                                    -120.37796
                                ],
                                "eta": "2023-10-01T10:30:00-08:00",
                                "timeToNext": 13,
                                "distanceToNext": 5.6,
                                "waitTime": 112,
                                "polyline": null,
                                "ordinal": 4
                            },
                            {
                                "jobId": 4,
                                "taskId": 6,
                                "type": "delivery",
                                "location": [
                                    50.66559,
                                    -120.36924
                                ],
                                "eta": "2023-10-01T12:45:00-08:00",
                                "timeToNext": 4,
                                "distanceToNext": 1.7,
                                "waitTime": 71,
                                "polyline": null,
                                "ordinal": 5
                            },
                            {
                                "break": 2,
                                "start": "2023-10-01T14:00:00-08:00",
                                "end": "2023-10-01T14:15:00-08:00",
                                "timeToNext": 7,
                                "distanceToNext": 3.2,
                                "waitTime": 217,
                                "polyline": null,
                                "ordinal": 6
                            }
                        ]
                    }
                ]
            },
            {
                "vehicleId": 2,
                "shifts": [
                    {
                        "index": 1,
                        "stops": [
                            {
                                "break": 1,
                                "start": "2023-10-01T11:00:00-08:00",
                                "end": "2023-10-01T11:15:00-08:00",
                                "timeToNext": 13,
                                "distanceToNext": 6.6,
                                "waitTime": 152,
                                "polyline": null,
                                "ordinal": 1
                            },
                            {
                                "jobId": 7,
                                "taskId": 8,
                                "type": "pickup",
                                "location": [
                                    50.70393,
                                    -120.37263
                                ],
                                "eta": "2023-10-01T14:00:00-08:00",
                                "timeToNext": 14,
                                "distanceToNext": 4.6,
                                "waitTime": 0,
                                "polyline": null,
                                "ordinal": 2
                            },
                            {
                                "jobId": 7,
                                "taskId": 9,
                                "type": "delivery",
                                "location": [
                                    50.69028,
                                    -120.39028
                                ],
                                "eta": "2023-10-01T14:29:00-08:00",
                                "timeToNext": 13,
                                "distanceToNext": 3.9,
                                "waitTime": 197,
                                "polyline": null,
                                "ordinal": 3
                            }
                        ]
                    }
                ]
            }
        ],
        "unassigned": []
    },
    "message": "success"
}

          "status": "in_progress",
          "vehicleId": 1,
          "eta": "2024-10-01T10:30:00-08:00"

          "status": "in_progress",
          "vehicleId": 1,
          "eta": "2024-10-01T12:45:00-08:00"

          "status": "in_progress",
          "vehicleId": 2,
          "eta": "2024-10-01T14:00:00-08:00"

          "status": "in_progress",
          "vehicleId": 2,
          "eta": "2024-10-01T14:29:00-08:00"

"lastKnownLocation":{
        "location":[50.66692,-120.35293],
        "time":"2024-10-01T11:36:34-08:00"
      } 

"lastKnownLocation":{
        "location":[50.65324,-120.37398],
        "time":"2024-10-01T11:36:34-08:00"
      } 

{
    "problem": {
        "fleet": [
            {
                "id": 1,
                "shifts": [
                    {
                        "start": {
                            "time": "2023-10-01T08:00:00-08:00",
                            "location": {
                                "lat": 50.67293,
                                "lng": -120.34195
                            }
                        },
                        "end": {
                            "time": "2023-10-01T18:00:00-08:00",
                            "location": {
                                "lat": 50.67293,
                                "lng": -120.34195
                            }
                        },
                        "breaks": [
                            {
                                "serviceWindow": [
                                    "2023-10-01T10:00:00-08:00",
                                    "2023-10-01T10:30:00-08:00"
                                ],
                                "duration": 900,
                                "location": {
                                    "lat": 50.6531,
                                    "lng": -120.38393
                                }
                            },
                            {
                                "serviceWindow": [
                                    "2023-10-01T14:00:00-08:00",
                                    "2023-10-01T14:30:00-08:00"
                                ],
                                "duration": 900,
                                "location": {
                                    "lat": 50.6531,
                                    "lng": -120.38393
                                }
                            }
                        ]
                    }
                ],
                "capacities": [
                    {
                        "name": "seat",
                        "units": 15
                    },
                    {
                        "name": "cargo",
                        "units": 5
                    }
                ],
                "skills": [
                    "lift",
                    "air_conditioner"
                ],
                "lastKnownLocation":{
                         "location":[50.66692,-120.35293],
                         "time":"2024-10-01T11:36:34-08:00"
               }                 
            },
            {
                "id": 2,
                "shifts": [
                    {
                        "start": {
                            "time": "2023-10-01T08:00:00-08:00",
                            "location": {
                                "lat": 50.7117,
                                "lng": -120.39286
                            }
                        },
                        "end": {
                            "time": "2023-10-01T18:00:00-08:00",
                            "location": {
                                "lat": 50.67698,
                                "lng": -120.32012
                            }
                        },
                        "breaks": [
                            {
                                "serviceWindow": [
                                    "2023-10-01T11:00:00-08:00",
                                    "2023-10-01T11:30:00-08:00"
                                ],
                                "duration": 900,
                                "location": {
                                    "lat": 50.6531,
                                    "lng": -120.38393
                                }
                            }
                        ]
                    }
                ],
                "capacities": [
                    {
                        "name": "seat",
                        "units": 10
                    },
                    {
                        "name": "cargo",
                        "units": 8
                    }
                ],
                "skills": [
                    "lift"
                ],
                "lastKnownLocation":{
                         "location":[50.65324,-120.37398],
                         "time":"2024-10-01T11:36:34-08:00"
               }                 
            }
        ],
        "jobs": [
            {
                "id": 1,
                "pickups": [
                    {
                        "id": 2,
                        "location": [
                            50.65391,
                            -120.37365
                        ],
                        "serviceWindows": [
                            [
                                "2023-10-01T09:00:00-08:00",
                                "2023-10-01T09:30:00-08:00"
                            ]
                        ],
                        "duration": 600,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 2
                            }
                        ],
                        "skills": [
                            "lift"
                        ],
                        "status": "performed"
                    }
                ],
                "deliveries": [
                    {
                        "id": 3,
                        "location": [
                            50.69409,
                            -120.35425
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 2
                            }
                        ],
                        "skills": [
                            "lift"
                        ],
                        "status": "performed"
                    }
                ]
            },
            {
                "id": 4,
                "pickups": [
                    {
                        "id": 5,
                        "location": [
                            50.70816,
                            -120.37796
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            }
                        ],
                        "skills": [
                            "lift",
                            "air_conditioner"
                        ],
                        "status": "in_progress",
                        "vehicleId": 1,
                        "eta": "2023-10-01T10:30:00-08:00"
                    }
                ],
                "deliveries": [
                    {
                        "id": 6,
                        "location": [
                            50.66559,
                            -120.36924
                        ],
                        "serviceWindows": [
                            [
                                "2023-10-01T12:45:00-08:00",
                                "2023-10-01T13:30:00-08:00"
                            ]
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            }
                        ],
                        "skills": [
                            "lift",
                            "air_conditioner"
                        ],
                        "status": "in_progress",
                        "vehicleId": 1,
                        "eta": "2023-10-01T12:45:00-08:00"
                    }
                ]
            },
            {
                "id": 7,
                "pickups": [
                    {
                        "id": 8,
                        "location": [
                            50.70393,
                            -120.37263
                        ],
                        "serviceWindows": [
                            [
                                "2023-10-01T14:00:00-08:00",
                                "2023-10-01T14:30:00-08:00"
                            ]
                        ],
                        "duration": 600,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 3
                            }
                        ],
                        "status": "in_progress",
                        "vehicleId": 2,
                        "eta": "2023-10-01T14:00:00-08:00"                        
                    }
                ],
                "deliveries": [
                    {
                        "id": 9,
                        "location": [
                            50.69028,
                            -120.39028
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 3
                            }
                        ],
                        "status": "in_progress",
                        "vehicleId": 2,
                        "eta": "2023-10-01T14:29:00-08:00"                       
                    }
                ]
            },
            {
                "id": 10,
                "pickups": [
                    {
                        "id": 11,
                        "location": [
                            50.65187,
                            -120.40052
                        ],
                        "serviceWindows": [
                            [
                                "2023-10-01T15:45:00-08:00",
                                "2023-10-01T16:15:00-08:00"
                            ]
                        ],
                        "duration": 900,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 1
                            }
                        ],
                        "status": "pending"
                    }
                ],
                "deliveries": [
                    {
                        "id": 12,
                        "location": [
                            50.69262,
                            -120.35412
                        ],
                        "duration": 600,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 1
                            }
                        ],
                        "status": "pending"
                    }
                ]
            }

        ],
        "objective": 1,
        "configuration": {
            "polylineType": "none",
            "unassignedTasks": true,
            "units": "imperial",
            "statistics": true
        }
    }
}

{
    "plugin": "internal;basic",
    "internal": {
        "email": "tenant2@ddswireless.com",
        "password": "AdM5I0N09ToS$IlJ",
        "tenantId": 2
    },
    "basic": {
        "username": "tenant2@ddswireless.com",
        "password": "AdM5I0N09ToS$IlJ",
        "tenantId": 2
    }
}

{
    "plugin": "internal;basic",
    "internal": {
        "email": "tenant3@ddswireless.com",
        "password": "AdM5I0N09ToS$IlJ",
        "tenantId": 3
    },
    "basic": {
        "username": "tenant3@ddswireless.com",
        "password": "AdM5I0N09ToS$IlJ",
        "tenantId": 3
    }
}

{
  "problem": {
    "fleet": [
      {
        "id": 1,
        "shifts": [
          {
            "start": {
              "time": "2023-10-01T08:00:00-08:00",
              "location": { "lat": 50.67293, "lng": -120.34195 }
            },
            "end": {
              "time": "2023-10-01T18:00:00-08:00",
              "location": { "lat": 50.67293, "lng": -120.34195 }
            },
            "breaks": [
              {
                "serviceWindow": ["2023-10-01T10:00:00-08:00", "2023-10-01T10:30:00-08:00"],
                "duration": 900,
                "location": { "lat": 50.6531, "lng": -120.38393 }
              },
              {
                "serviceWindow": ["2023-10-01T14:00:00-08:00", "2023-10-01T14:30:00-08:00"],
                "duration": 900,
                "location": { "lat": 50.6531, "lng": -120.38393 }
              }
            ]
          }
        ],
        "capacities": [
          {
            "name": "seat",
            "units": 15
          },
          {
            "name": "baggage",
            "units": 5
          }
        ],
        "skills": ["lift", "air_conditioner"]
      },
      {
        "id": 2,
        "shifts": [
          {
            "start": {
              "time": "2023-10-01T08:00:00-08:00",
              "location": { "lat": 50.7117, "lng": -120.39286 }
            },
            "end": {
              "time": "2023-10-01T18:00:00-08:00",
              "location": { "lat": 50.67698, "lng": -120.32012 }
            },
            "breaks": [
              {
                "serviceWindow": ["2023-10-01T11:00:00-08:00", "2023-10-01T11:30:00-08:00"],
                "duration": 900,
                "location": { "lat": 50.6531, "lng": -120.38393 }
              }
            ]
          }
        ],
        "capacities": [
          {
            "name": "seat",
            "units": 10
          },
          {
            "name": "baggage",
            "units": 8
          }
        ],
        "skills": ["lift"]
      }
    ],
    "jobs": [
      {
        "id": 1,
        "pickups": [
          {
            "id": 2,
            "location": [50.65391, -120.37365],
            "serviceWindows": [["2023-10-01T09:00:00-08:00", "2023-10-01T09:30:00-08:00"]],
            "duration": 600,
            "demand": [
              {
                "name": "seat",
                "units": 1
              },
              {
                "name": "baggage",
                "units": 2
              }
            ],
            "skills": ["lift"]
          }
        ],
        "deliveries": [
          {
            "id": 3,
            "location": [50.69409, -120.35425],
            "duration": 300,
            "demand": [
              {
                "name": "seat",
                "units": 1
              },
              {
                "name": "baggage",
                "units": 2
              }
            ],
            "skills": ["lift"]
          }
        ]
      },
      {
        "id": 4,
        "pickups": [
          {
            "id": 5,
            "location": [50.70816, -120.37796],
            "duration": 300,
            "demand": [
              {
                "name": "seat",
                "units": 1
              }
            ],
            "skills": ["lift", "air_conditioner"]
          }
        ],
        "deliveries": [
          {
            "id": 6,
            "location": [50.66559, -120.36924],
            "serviceWindows": [["2023-10-01T12:45:00-08:00", "2023-10-01T13:30:00-08:00"]],
            "duration": 300,
            "demand": [
              {
                "name": "seat",
                "units": 1
              }
            ],
            "skills": ["lift", "air_conditioner"]
          }
        ]
      },
      {
        "id": 7,
        "pickups": [
          {
            "id": 8,
            "location": [50.70393, -120.37263],
            "serviceWindows": [["2023-10-01T14:00:00-08:00", "2023-10-01T14:30:00-08:00"]],
            "duration": 600,
            "demand": [
              {
                "name": "seat",
                "units": 1
              },
              {
                "name": "baggage",
                "units": 3
              }
            ]
          }
        ],
        "deliveries": [
          {
            "id": 9,
            "location": [50.69028, -120.39028],
            "duration": 300,
            "demand": [
              {
                "name": "seat",
                "units": 1
              },
              {
                "name": "baggage",
                "units": 3
              }
            ]
          }
        ]
      }
    ],
    "objective": 1,
    "configuration": {
        "polylineType": "none",
        "unassignedTasks": true,
        "units" : "imperial",
        "statistics" : true
    }
  }
}

Step 3: Get the output response of the API call

To get the output response of the API call using the received reference ID, put the access token in the “Authorization” part of the following GET request, and include the reference ID in the URL as follows:

GET URL: https://iq.aiqwhite.ddsdeploytest.com/raas/optimization/{ID}

Here is a screenshot of this step:

API Errors #

As described in Get Started, the API supports both POST and GET methods. Depending on the method, it returns a status code in the output response. Here, you can find the description of various status codes for these two methods.

POST Status Codes #

GET Status Codes #

FAQ #