NAV Navbar
http+json shell

Introduction

The WorkWave Routing Engine (WWRE) is a service that exposes routing, scheduling and routing-optimization functionalities via a REST Application Programming Interface (API) endpoints. This document is the official reference for that service.

Basic concepts

The API is entirely HTTP-based

Methods to retrieve data from the API require a GET request. Methods that submit or change data require a POST. Methods that destroy data require a DELETE. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct one. HTTP Response Codes are meaningful.

The API is a RESTful resource

The API attempts to conform to the design principles of Representational State Transfer (REST).

Libraries to build REST-compatible API clients are readily available for several programming languages.

The format used for structured data exchange is JSON

The API supports the JSON (JavaScript Object Notation) format. Details on how JSON works can be found here and here. Libraries that convert to and from the JSON format are readily available for popular and lesspopular programming languages. A full index, sorted by language, can be found at the bottom of this page

The API works with both plain HTTP and HTTP-within-SSL/TLS (HTTPS).

HTTPS is highly recommended to avoid passing both the authentication KEY and potentiallyconfidential data (e.g.: client's geocoded locations) in clear text over the web.

Parameters have certain expectations

Some API methods take optional or requisite parameters. Please keep in mind that allquery-string parameter values should be converted to UTF-8 and URL encoded.

There is one special parameter in the API, key, used for authentication, see section belowfor more details.

Authentication

Authentication is performed using an API key (also called as Account) provided by WorkWave. The API key must be included in the HTTP(S) request using one of the following two methods:

Where both are provided the query-string parameter takes precedence.

The API key is a string formatted as AAAA-AAAA-AAAA-AAAA.

Concurrency

There is a limit on the maximum number of API requests that can be concurrently submitted from the same key.
This limit is "1" for the Optimization resource, that is: each API account can run one optimization at a time.

Asynchronous Requests

Optimization requests are syncronous, for default, but they can be made as asyncronous. All asynchronous requests return immediately with a RequestId, a string that identify a specific request, more specifically it is a UUID in its canonical form (e.g.: "123e4567-e89b-12d3-a456-426655440000").
The RequestId can be used for retriving an optimization result.

Notifications

The WorkWave Routing Engine API supports a notification mechanism based on HTTP callbacks (aka WebHooks).
A callback URL is defined on a optimization request basis to receive event notifications when optimization request ends. Notification messages are POSTed to the callback URL.

Queueing and Throttling

All requests are queued on a per-key (aka Account) basis and processed one by one in the order they have been queued (FIFO).
The queue has a maximum size of 25 items. Attempting to queue more than this number of requests will return a "Too Many Requests" error.
Throttling and rate-limiting schemes are applied on a per-key to both synchronous and asynchronous requests to prevent overloading the system with too many / too fast requests.

Versioning and evolution

WorkWave Routing Engine API is constantly evolving. Existing methods are being improved and extended and new functionalities are being added.

Backward-compatible changes are implemented as extensions to existing versions, while backward-incompatible changes are implemented by introducing entirely new versions.

While we are strongly committed to never introduce breaking changes to existing versions, integration code must be flexible enough to handle backward-compatible updates gracefully.

Here is a list of backward-compatible changes together with how integration code is supposed to deal with them.

Introducing a new REST resource

This is never a problem as existing integration code, not knowing about new endpoints, will not use them.

Adding properties to existing response objects

Existing integration code should ignore unmapped fields.

Note: Some JSON libraries, most notably Jackson, by default will throw an error in case an unmapped field is encountered during parsing. It is important that such libraries are configured to ignore (and possibly report) unmapped fields rather than fail.

Adding optional properties to existing request objects

This is never a problem as existing integration code, not knowing about the new fields, will not populate them.

Adding new values to existing enums in request objects

This is never a problem as existing integration code, not knowing about the new values, will not use them.

Adding new values to existing enums in response objects

This is trickier and we try to limit it only to cases where the change can be handled in a backward-compatible way. Existing integration code should ignore ExecutionEvents with an unknown type and it is recommended to log these events to keep track of them.

HTTP Status Codes

The WorkWave Routing Engine API attempts to return appropriate HTTP status codes for every request.

Error Code
Description
200 OK -- Success
400 Bad Request -- The request cannot be accepted. The accompanying error message explains why.
401 Unauthorized -- Authentication credentials are missing or incorrect.
403 Forbidden -- The resource requested is hidden for administrators only.
404 Not Found -- The URI requested is invalid or the resource requested does not exists.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that is not available (e.g. xml).
429 Too Many Requests -- Rate limit exceeded. Wait before retrying and reduce the rate of requests.
500 Internal Server Error -- We had a problem with the service. The WorkWave Routing Engine support team is automatically alerted when this error happens but you may wish to contact them directly to provide additional details to help in the resolution.
502 Bad Gateway -- the service is temporarily down or being upgraded.
503 Service Unavailable -- The WorkWave Routing Engine servers are up, but overloaded with requests. Try again later.

Error Codes and Messages

{
  "errorCode": -1000,
  "errorDescription": "Failed parsing JSON source"
}

When the WorkWave Routing Engine API returns error messages, it does so in JSON format. See examples in the right panel.

Error codes, as found in the body of returned error messages, further define the scope of an error.
The following error codes may be returned:

Error Code
Description
-100 Internal Error -- An unexpected internal error happened that prevented the request to be fully completed. You may try again later but, in case you would like to investigate the issue please contact WWRE support.
-200 Unknown Key -- Wrong authentication key.
-400 License Limit Exceeded -- The request is formally correct but a licensing limit has been exceeded. One or more constraints associated with the authentication key, such as maximum number of Vehicles or Waypoints, have been exceeded.
-401 License Expired -- The authentication key is expired. Contact WWRE support for a renewal.
-700 Unknown Matrix -- The specified matrix does not exist.
-701 Matrix Already Exists -- The specified Matrix already exists.
-900 Too Many Requests -- The given key has submitted too many requests in too short a period of time. Insert a pause between requests to avoid getting this error.
-1000 Malformed Request -- Something is wrong with the request. It could be that the JSON data in the request body is malformed (typically due to a missing or overabundant parenthesis or comma) or a mandatory field is missing or a negative value has been set for a field that expects a positive integer, etc
-1100 Unknown Request -- No request exists for the specified request ID.
-1102 Invalid Request -- Invalid request, for example to delete a request that has already been completed.
-1103 Expired Request Result -- We keep the result of a request for a limited amount of time, this is set to a couple of days but it can be changed, so when a request's result is expired it will be removed from the cache.
-1300 Resource Not Found -- Trying to access a resource that not exists, for example and invalid endpoint.

REST Client

To start experimenting with a few examples we recommend a REST client called Postman, an handy API client that facilitates testing and experimenting with RESTful endpoints.

Installing Postman

You can ownload the Postman App for Windows, OS X, or Linux or you can use Postman online:

API Overview

The WorkWave Routing Engine API, exposed from the domain wwre.workwave.com, includes the following RESTful resources to integrate with.

Each resource is further detailed later in its own chapter.

Optimization Concepts

Optimizes a set of waypoints so that they are best allocated to a set of vehicles taking into account the following complex constraints:

Optimization Goals

The optimization goals are defined by the following list of priorities:

Some examples of how costs can be tweaked to model different scenarios:

Optimization and Matrix

The maximum allowed size of a single optimization (single day or multi day) request varies according to the size of the purchased plan.

The size of an optimization request cannot exceed the account fleet size and the route plan size (in terms of the number of vehicles and waypoints included in the request). Note that multiple waypoints sharing the same coordinates count as their number and not as one and the same applies to vehicles.

There is no limit on the number of optimization requests that can be submitted, if their size and vehicle usage is allowed by the purchased plan. Too many or too frequent requests may be temporarily rejected with error code -900 (see Error Codes and Messages for details).

Optimizations can be "one-shot" or bound to a specific Matrix (identified by its matrix id).

For a "one-shot" optimization the process is:

  1. compute full driving duration Matrix against road network
  2. optimize problem and discard Matrix

For an optimization bound to a Matrix the process changes as follows:

  1. compute delta driving duration Matrix against road network
  2. optimize problem
  3. save updated Matrix

Bounding to a Matrix is especially useful when multiple optimizations are performed against the same or similar set of vehicles/waypoints. In such scenarios, at every new optimization request only a delta-matrix has to be computed thus greatly speeding up the whole process for quicker response times.

Note that the Matrix data is implicitly and automatically updated at every optimization request bound to that Matrix. Matrices can be created, listed and deleted but cannot be manipulated in any other way if not by the result of an optimization. A Matrix should therefore be considered as a simple "named token" to be used with the Optimization resource.

Asynchronous Optimizations

An optimization request can take from a few seconds up to several minutes to complete, depending on its size, constraints complexity and on the average and maximum reciprocal distance between all involved locations.

For larger/more complex invocations where the expected processing time is longer than a few seconds it is recommended to use the asynchronous mode to avoid dropped TCP connection issues. Currently the TCP idle connection time is set to 120 seconds, so if a synchronous request required more than 120 seconds will be forcefully closed.

The asynchronous mode is activated by setting the async parameter to true in the input request, which is otherwise identical to the one described on the object definition for SingleDayOptimizationRequest and MultiDayOptimizationRequest.

Asynchronous requests return immediately providing just the request identification (called requestId or reqId), which can then be used to poll for status updates and to retrieve the result when the request is completed.

Asynchronous Optimization Response

An optimization response for an asynchronous request that is not yet compleated have the format of AsyncOptimizationResponse.

The status field can be PROCESSING or QUEUED. A queued request means that the user has one or more requests that are already executing. These requests must be completed before executing a queued one.

The progress field is an integer value in the range 0-100 indicating the completion of the request in 1% percent steps.

The resultAvailable field states if an optimization result is available. In this way, if the optimization is cancelled with keepResult flag enabled, current result is provided as optimization result.

Advanced Scenarios

Below few advanced scenarios and topics that can be model with the optimization API.

Flexibile Time-Windowed Traffic

A request example with the use of flexible traffic management. See Single-Day Optimization API and Multi-Day Optimization API for details.

{
    "traffic": {
        "trafficTimeWindows": [
            {
                "startTimeSec": 36000,
                "stopTimeSec": 39600
            },
            {
                "startTimeSec": 46000,
                "stopTimeSec": 49600
            }
        ],
        "trafficProfiles": {
            "holiday": {
                "trafficRegions": [
                    {
                        "region": [
                            "..."
                        ],
                        "trafficFactor": 1,
                        "twTrafficFactors": [
                            1.5,
                            2.0
                        ]
                    }
                ],
                "baseTrafficFactor": 1
            },
            "weekday": {
                "trafficRegions": [
                    {
                        "region": [
                            "..."
                        ],
                        "trafficFactor": 1.7,
                        "twTrafficFactors": [
                            2.8,
                            4.5
                        ]
                    }
                ],
                "baseTrafficFactor": 1.5
            }
        }
    },
    "vehicles": [
        {
            "name": "Vehicle A",
            "daySettings": {
                // a friday      
                "1": {
                    "trafficProfile": "weekday",
                    "// ...": null
                },
                // a saturday
                "2": {
                    "trafficProfile": "holiday",
                    "// ...": null
                }
            }
        }
    ],
    "waypoints": [
        "..."
    ]
}

The API allows multiple Traffic Profiles to be defined and individually assigned to vehicles or, when using the multiday endpoint, to vehicle-day pairs. This enables modeling multiday scenarios with horizons spanning both week days and holidays where traffic is shaped differently according to the day of the week. Take a look of the example on the right panel.

Minimum Requirements

A request example with that use Minimum Requirements. See Vehicle object for details.

{
  "vehicles": [
    {
      "name": "Van #1",
      "daySettings": {
        "1": {
          "minCapacityMap": {
            "pounds": 10_000,
            "visitedWaypoints": 15
          },
          "minWorkingTimeSec": 34000,
          // more vehicle settings
          ... 
        }
      }
    },
    // more vehicles
    ... 
  ],
  "waypoints": [...]
}

Minimum Requirements (MR) are a set of "best effort" minimum acceptable constraints that can be defined into a vehicle object for a route to be acceptable/valid:

These are not hard constraints but they are a "best effort", meaning that they can be violated if by doing so results if better optimization results (i.e.: less costly solution).

By their nature MR work at their best:

Reloading at Depots

A request example with Pickups/Dropoffs and loads.

{
  "vehicles": [
    {
      "name": "ve1",
      "maxCapacityMap": {
        "refrigerators": 3,
        "ovens": 2
      },
      "origin": {
        "latitude": 42.35516,
        "longitude": -71.76032
      },
      "timeWindow": {
        "startTimeSec": 27000,
        "stopTimeSec": 121000
      },
      "destination": {
        "latitude": 42.35516,
        "longitude": -71.76032
      }
    }
  ],
  "waypoints": [
    {
      "name": "dropoff1",
      "location": {
        "latitude": 42.38246,
        "longitude": -71.33345
      }
    },
    {
      "name": "pickup1",
      "location": {
        "latitude": 42.53996,
        "longitude": -71.41965
      },
      "dropoffNumber": 0,
      "pickupMap": {
        "refrigerators": 2
      },
      "serviceTimeSec": 300,
      "timeWindows": [
        {
          "startTimeSec": 28800,
          "stopTimeSec": 43200
        },
        {
          "startTimeSec": 46800,
          "stopTimeSec": 61200
        }
      ]
    },
    {
      "name": "dropoff1",
      "location": {
        "latitude": 42.38246,
        "longitude": -71.33345
      }
    },
    {
      "name": "pickup2",
      "location": {
        "latitude": 42.44266,
        "longitude": -71.52767
      },
      "dropoffNumber": 2,
      "pickupMap": {
        "refrigerators": 2
      },
      "serviceTimeSec": 900,
      "timeWindows": [
        {
          "startTimeSec": 28800,
          "stopTimeSec": 43200
        },
        {
          "startTimeSec": 46800,
          "stopTimeSec": 61200
        }
      ]
    },
    {
      "name": "dropoff2",
      "location": {
        "latitude": 42.48246,
        "longitude": -71.23421
      },
      "deliveryMap": {
        "refrigerators": 1,
        "ovens": 1
      }
    },
    {
      "name": "pickup3",
      "location": {
        "latitude": 42.45829,
        "longitude": -71.69517
      },
      "dropoffNumber": 4,
      "pickupMap": {
        "refrigerators": 1,
        "oven": 1
      },
      "serviceTimeSec": 1200,
      "timeWindows": [
        {
          "startTimeSec": 28800,
          "stopTimeSec": 43200
        },
        {
          "startTimeSec": 46800,
          "stopTimeSec": 61200
        }
      ]
    }
  ]
}

Scenarios where vehicles have a limited load capacity but plenty of working time and may require returning to a depot one or more times through the course of their route to reload.

These scenarios can be modeled using the existing Pickup&Delivery (P&D) constraints. Multiple deliveries where all items to be delivered are stored at a central depot can model each delivery as two waypoints: one pickup waypoint located at the depot and one delivery waypoint, linked to its pickup, at the actual delivery destination.

Existing P&D heuristics have been extended to also handle reload scenarios where there is typically a multitude of waypoints sharing the same location (the depot or depots).

There are typically two Reload scenarios:

Clustering

Clusters may be used to model several situations in which the driving times and the costs associated with the vehicles are not enough to grasp all the complexities that occur in real-world logistic problems. Both waypoints (see Cluster object) and vehicle origin / destination depot (see members originClusters and destinationClusters in Vehicle object) can belong to one or more clusters.

Clustering Overview

When it needs to determine the driving times and the costs associated with the route from a point P (the vehicle origin depot or a waypoint) to another point Q (a waypoint or the vehicle destination depot) or the service time associated with Q when it is preceded by P, the Routing Engine applies the following rules:

Note that the increment in driving/service time related to the application of previous rules will not impact on computation of driving time and service time during the route cost computation described in section Optimization Goals (in order to modify route cost using clusters you need to correctly set the enterCost and exitCost members of your clusters, see objects Clustering and Vehicle).

Clustering scenario

A request example that models the problem using clusters

{
    "clustering": {
        "clusters": {
            "cluster 1": {
                "enterCost": 100,
                "exitCost": 200,
                "setupTimeSec": 60
            },
            "cluster 2": {
                "setupCost": 100,
                "setupTimeSec": 120,
                "enterTimeSec": 100,
                "exitTimeSec": 200
            },
            "cluster 3": {
                "enterCost": 100,
                "exitCost": 50,
                "requireVehicleStop": true
            }
        },
        "intersectionFunctions": {
            "enterTime": "SUM",
            "exitTime": "AVG",
            "enterCost": "MIN",
            "exitCost": "MAX"
        }
    },
    "vehicles": [
        {
            "name": "Vehicle A",
            "daySettings": {
                "1": {
                    "originClusters": [
                        "cluster 1"
                    ],
                    "destinationClusters": [
                        "cluster 2"
                    ]
                }
            }
        }
    ],
    "waypoints": [
        {
            "name": "wp 1",
            "clusters": [
                "cluster 1"
            ],
            // ...
        },
        {
            "name": "wp 2",
            "clusters": [
                "cluster 2",
                "cluster 3"
            ],
            // ...
        },
        // ...
    ]
}

This feature allows clustering waypoints together and applying driving time and cost penalties for vehicles entering or exiting the cluster.

Entering a cluster means driving from a waypoint that does not belong to the cluster to a waypoint that belongs to the cluster. Vice versa for exiting a cluster.

Clusters are not (necessarily) geographical entities, they are abstract grouping entities.
A cluster defines the following properties:

Clustering helps model scenarios where it is desirable that a vehicle driving to a certain area stays there serving all nearby waypoints, possibly waiting for a time window to open rather then driving back and forth between different areas to avoid idle time because moving between areas is costly in terms of tolls or driving time.

Clustering also helps model Reload scenarios where reloading at depots incurs a fixed setup time & cost which is unrelated to the number/amount of goods that are loaded (e.g. fixed time required to dock a truck):

Clustering scenario

Clustering reload scenario

Road Segment Exceptions

Request format with segment exceptions

{  
    "routings": {
        "default": {
            "exceptions": [{
                "start": {...},
                "end": {...},
                // specify either
                "malus": 8, // valid range [-10, 10]
                // or
                "additionalDrivingTimeSec": 1800
            },
            //... more exceptions
            ]
        }
    },
  // ...
}

Another example for blocking bridge crossing

{
  "routings": {
    "default": {
      "exceptions": [
        // ban Champlain bridge
        {
          "start": { "latitude": 45.471807, "longitude": -73.520317 },
          "end": { "latitude": 45.464674, "longitude": -73.520103 },
          "malus": 10
        },
        // crossing Victoria bridge incurs a 30mins driving time penalty
        {
          "start": { "latitude": 45.494071, "longitude": -73.533081 },
          "end": { "latitude": 45.488531, "longitude": -73.528191 },
          "additionalDrivingTimeSec": 1800
        },
        // strongly discourage using Tunnel Louis-Hippolyte
        {
          "start": { "latitude": 45.585302, "longitude": -73.500884 },
          "end": { "latitude": 45.582266, "longitude": -73.501701 },
          "malus": 8
        }
      ]
    }
  },
  "vehicles": [...],
  "waypoints": [...],
  // ... rest of the optimization request here
}

The exception segments drawn on the map by the exception above:

Segment exception bridge

Directly affects routing (i.e.: how driving and mileage matrices are computed) and helps model the following scenarios:

Each Exception object must have both start and end coordinates and either a malus or an additionalDrivingTimeSec parameter.

malus ranges from -10 to 10 where:

Matrix API

List Matrices

curl https://wwre.workwave.com/opt/v5/matrix?key=AUTH_KEY
GET https://wwre.workwave.com/opt/v5/matrix HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com

The above command returns JSON structured like this:

{
  "matrices": [
    {
      "id": 550,
      "name": "myFirstMtx",
      "creationDate": 1286446431000
    },
    {
      "id": 551,
      "name": "mySecondMtx",
      "creationDate": 1286446437000
    }
  ]
}

List available Matrices with their name and ID.

HTTP Request

GET https://wwre.workwave.com/opt/v5/matrix

Execution Type

Synchronous

Throttling

Rate-limit (5 call every 60 seconds)

Return Values

Property Type Description
matrices List of Matrix List of matrices available and created by user's key

Create Matrix

curl –X POST https://wwre.workwave.com/opt/v5/matrix?key=AUTH_KEY&name=myMtx
POST https://wwre.workwave.com/opt/v5/matrix?&name=myMtx HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com

The above command returns JSON structured like this:

{
  "id":551,
  "name":"myMtx",
  "creationDate":1286455766735
}

Create an empty Matrix to be used with an optimization resource.

HTTP Request

POST https://wwre.workwave.com/opt/v5/matrix[?name=myMtx]

Execution Type

Synchronous

Throttling

Rate-limit (10 call every 60 seconds)

QueryString Parameters

Property Type Description
name String Optional. Name assigned to the matrix

Return Values

Matrix

Delete Matrix

curl -X DELETE https://wwre.workwave.com/opt/v5/matrix/id/551?key=AUTH_KEY
curl -X DELETE https://wwre.workwave.com/opt/v5/matrix/name/myMtx?key=AUTH_KEY
DELETE https://wwre.workwave.com/opt/v5/matrix/id/551 HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com
DELETE https://wwre.workwave.com/opt/v5/matrix/name/myMtx HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com

Delete a Matrix.

HTTP Request

A matrix can be referred by name or matrix identification:

Execution Type

Synchronous

Throttling

Rate-limit (10 call every 60 seconds)

Path Parameters

Property Type Description
matrixId Integer The matrix identification, mutually exclusive with matrixName
matrixName String The matrix name, mutually exclusive with matrixId

Return Values

[Empty Response Body]

Single-Day Optimization API

Optimization that works on a single execution day.

Compute Single-Day Optimization


curl -X POST https://wwre.workwave.com/opt/v5/optimization?key=AUTH_KEY \
    "Content-Type: application/json" \
    -d "@request.json"
curl -X POST https://wwre.workwave.com/opt/v5/optimization/id/551?key=AUTH_KEY \
     "Content-Type: application/json" \
     -d "@request.json"
curl -X POST https://wwre.workwave.com/opt/v5/optimization/name/myMtx?key=AUTH_KEY \
     "Content-Type: application/json" \
     -d "@request.json"

Where request.json is a file containing the JSON data to be posted
POST https://wwre.workwave.com/opt/v5/optimization HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com
Content-Type: application/json
POST https://wwre.workwave.com/opt/v5/optimization/id/551?key=AUTH_KEY HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com
Content-Type: application/json
POST https://wwre.workwave.com/opt/v5/optimization/name/myMtx?key=AUTH_KEY HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com
Content-Type: application/json
{
  "vehicles": [
    {
      "name": "Vehicle A",
      "origin": {
        "latitude": 42.35516,
        "longitude": -71.76032
      },
      "timeCostModel": {
        "drivingTimeCostFactor": 5000,
        "serviceTimeCostFactor": 5000,
        "idleTimeCostFactor": 5000,
        "breakTimeCostFactor": 5000
      },
      "distanceCostFactor": 100,
      "timeWindow": {
        "startTimeSec": 40000,
        "stopTimeSec": 80000
      },
      "destination": {
        "latitude": 42.35516,
        "longitude": -71.76032
      }
    }
  ],
  "waypoints": [
    {
      "name": "wp 1",
      "location": {
        "latitude": 42.38246,
        "longitude": -71.33345
      },
      "serviceTimeSec": 900
    },
    {
      "name": "wp 2",
      "location": {
        "latitude": 42.4559,
        "longitude": -71.52353
      }
    },
    {
      "name": "wp 3",
      "location": {
        "latitude": 42.53996,
        "longitude": -71.41965
      }
    }
  ]
}

The above command returns JSON structured like this:

Asynchronous response

{
  "reqID": "4e0e9137-8dc5-42ff-aa83-23e1865aeca2",
  "status": "PROCESSING",
  "progress": 33,
  "resultAvailable": false,
  "queuePosition": 0
}

Synchronous response

{
  "reqID": "dd0ef471-6223-427b-9017-ffc6dd4688a1",
  "status": "COMPLETED",
  "matrixID": -1,
  "elapsedSec": 0,
  "routes": [
    {
      "vehicle": {
        "number": 0,
        "name": "Vehicle A"
      },
      "routeStats": {
        "breakTimeSec": 0,
        "driveTimeSec": 9495,
        "idleTimeSec": 0,
        "serviceTimeSec": 900,
        "workTimeSec": 10395,
        "distanceMt": 135736,
        "perStopSetupTimeSec": 0,
        "perStopSetupCost": 0,
        "clusterSetupTimeSec": 0,
        "clusterEnterTimeSec": 0,
        "clusterExitTimeSec": 0,
        "clusterEnterCost": 0,
        "clusterExitCost": 0
      },
      "cost": 65548600,
      "steps": [
        {
          "stepNumber": 0,
          "waypoint": {
            "name": "origin",
            "number": -1
          },
          "latitude": 42.35516,
          "longitude": -71.76032,
          "timeWindow": {
            "startTimeSec": 40000,
            "stopTimeSec": 80000
          },
          "arrivalTimeSec": 0,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 0,
          "departureTimeSec": 40000,
          "nextStepDriveTimeSec": 2693,
          "nextStepDistanceMt": 52553,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 0,
            "idleTimeSec": 0,
            "serviceTimeSec": 0,
            "workTimeSec": 0,
            "distanceMt": 0,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        },
        {
          "stepNumber": 1,
          "waypoint": {
            "name": "wp 3",
            "number": 2
          },
          "latitude": 42.53996,
          "longitude": -71.41965,
          "arrivalTimeSec": 42693,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 42693,
          "departureTimeSec": 42693,
          "nextStepDriveTimeSec": 2436,
          "nextStepDistanceMt": 26830,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 2693,
            "idleTimeSec": 0,
            "serviceTimeSec": 0,
            "workTimeSec": 2693,
            "distanceMt": 52553,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        },
        {
          "stepNumber": 2,
          "waypoint": {
            "name": "wp 1",
            "number": 0
          },
          "latitude": 42.38246,
          "longitude": -71.33345,
          "arrivalTimeSec": 45129,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 45129,
          "departureTimeSec": 46029,
          "nextStepDriveTimeSec": 2447,
          "nextStepDistanceMt": 22595,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 5129,
            "idleTimeSec": 0,
            "serviceTimeSec": 900,
            "workTimeSec": 6029,
            "distanceMt": 79383,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        },
        {
          "stepNumber": 3,
          "waypoint": {
            "name": "wp 2",
            "number": 1
          },
          "latitude": 42.4559,
          "longitude": -71.52353,
          "arrivalTimeSec": 48476,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 48476,
          "departureTimeSec": 48476,
          "nextStepDriveTimeSec": 1919,
          "nextStepDistanceMt": 33758,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 7576,
            "idleTimeSec": 0,
            "serviceTimeSec": 900,
            "workTimeSec": 8476,
            "distanceMt": 101978,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        },
        {
          "stepNumber": 4,
          "waypoint": {
            "name": "destination",
            "number": -2
          },
          "latitude": 42.35516,
          "longitude": -71.76032,
          "arrivalTimeSec": 50395,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 0,
          "departureTimeSec": 50395,
          "nextStepDriveTimeSec": 0,
          "nextStepDistanceMt": 0,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 9495,
            "idleTimeSec": 0,
            "serviceTimeSec": 900,
            "workTimeSec": 10395,
            "distanceMt": 135736,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        }
      ]
    }
  ],
  "unreachedWaypoints": [],
  "unreachableWaypoints": [],
  "unneededVehicles": [],
  "warnings": []
}

Perform a single day optimization request, that can refers or not a pre-generated matrix. If a request do not use a matrix (so called one-shot request), a distance/time matrix will be computed and, at the end of computation, deleted.

HTTP Request

One-Shot HTTP Request

POST https://wwre.workwave.com/opt/v5/optimization

Matrix Based HTTP Request

A matrix can be referred by name or matrix identification:

Execution Type

Throttling

Leaky bucket (size: 60, refill: 5 per minute)

Path Parameters

Property Type Description
matrixId Integer Optional. The matrix identification, mutually exclusive with matrixName
matrixName String Optional. The matrix name, mutually exclusive with matrixId

Request Body

SingleDayOptimizationRequest (Request example)

Return Value (synchronous)

SingleDayOptimizationResponse (Response example)

Return Value (asynchronous)

AsyncOptimizationResponse

Get Single-Day Optimization

curl https://wwre.workwave.com/opt/v5/optimization/96cb6dcb-3841-489a-bbdc-b95460290362?key=AUTH_KEY
GET https://wwre.workwave.com/opt/v5/optimization/96cb6dcb-3841-489a-bbdc-b95460290362 HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com

The above command returns JSON structured like this:

Optimization not yet compleated response

{
  "reqID": "96cb6dcb-3841-489a-bbdc-b95460290362",
  "status": "PROCESSING",
  "progress": 33,
  "resultAvailable": false,
  "queuePosition": 0
}

Optimization compleated response

{
  "reqID": "96cb6dcb-3841-489a-bbdc-b95460290362",
  "status": "COMPLETED",
  "matrixID": -1,
  "elapsedSec": 1,
  "routes": [
    {
      "vehicle": {
        "number": 0,
        "name": "Vehicle A"
      },
      "routeStats": {
        "breakTimeSec": 0,
        "driveTimeSec": 9495,
        "idleTimeSec": 0,
        "serviceTimeSec": 900,
        "workTimeSec": 10395,
        "distanceMt": 135736,
        "perStopSetupTimeSec": 0,
        "perStopSetupCost": 0,
        "clusterSetupTimeSec": 0,
        "clusterEnterTimeSec": 0,
        "clusterExitTimeSec": 0,
        "clusterEnterCost": 0,
        "clusterExitCost": 0
      },
      "cost": 65548600,
      "steps": [
        {
          "stepNumber": 0,
          "waypoint": {
            "name": "origin",
            "number": -1
          },
          "latitude": 42.35516,
          "longitude": -71.76032,
          "timeWindow": {
            "startTimeSec": 40000,
            "stopTimeSec": 80000
          },
          "arrivalTimeSec": 0,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 0,
          "departureTimeSec": 40000,
          "nextStepDriveTimeSec": 2693,
          "nextStepDistanceMt": 52553,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 0,
            "idleTimeSec": 0,
            "serviceTimeSec": 0,
            "workTimeSec": 0,
            "distanceMt": 0,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        },
        {
          "stepNumber": 1,
          "waypoint": {
            "name": "wp 3",
            "number": 2
          },
          "latitude": 42.53996,
          "longitude": -71.41965,
          "arrivalTimeSec": 42693,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 42693,
          "departureTimeSec": 42693,
          "nextStepDriveTimeSec": 2436,
          "nextStepDistanceMt": 26830,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 2693,
            "idleTimeSec": 0,
            "serviceTimeSec": 0,
            "workTimeSec": 2693,
            "distanceMt": 52553,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        },
        {
          "stepNumber": 2,
          "waypoint": {
            "name": "destination",
            "number": -2
          },
          "latitude": 42.35516,
          "longitude": -71.76032,
          "arrivalTimeSec": 50395,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 0,
          "departureTimeSec": 50395,
          "nextStepDriveTimeSec": 0,
          "nextStepDistanceMt": 0,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 9495,
            "idleTimeSec": 0,
            "serviceTimeSec": 900,
            "workTimeSec": 10395,
            "distanceMt": 135736,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        }
      ]
    }
  ],
  "unreachedWaypoints": [],
  "unreachableWaypoints": [],
  "unneededVehicles": [],
  "warnings": []
}

Return the outcome or the status of a single-day optimization. The body returned by this invocation is identical to the one that would have been returned by a synchronous invocation, error responses included (in case the optimization failed for some reason).

If the optimization request is asynchronous and is not yet completed, the response is limited to the request identification and the status parameters.

HTTP Request

GET https://wwre.workwave.com/opt/v5/optimization/:reqId

Execution Type

Synchronous

Throttling

Leaky bucket (size: 60, refill: 5 per minute)

Path Parameters

Property Type Description
reqId UUID The request identification

Return Value

Delete Single-Day Optimization

curl –X DELETE https://wwre.workwave.com/opt/v5/optimization/96cb6dcb-3841-489a-bbdc-b95460290362?key=AUTH_KEY
curl –X DELETE https://wwre.workwave.com/opt/v5/optimization/96cb6dcb-3841-489a-bbdc-b95460290362?key=AUTH_KEY&keepResult=true
DELETE https://wwre.workwave.com/opt/v5/optimization/96cb6dcb-3841-489a-bbdc-b95460290362 HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com
DELETE https://wwre.workwave.com/opt/v5/optimization/96cb6dcb-3841-489a-bbdc-b95460290362?keepResult=true HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com

If the request is already completed or canceled

{
  "errorCode": -1102,
  "errorDescription": "Can't abort request with ID [96cb6dcb-3841-489a-bbdc-b95460290362] that has already been completed"
}

Cancel an asynchronous single-day optimization request.

If the request is queued will be removed from the queue, if the request is already completed or canceled a cancel command will be ignored (caller will be informed with a warning message), while if the request is processing will be forcefully terminated.

HTTP Request

DELETE https://wwre.workwave.com/opt/v5/optimization/:reqId[?keepResult=<Boolean>]

Execution Type

Synchronous

Throttling

Leaky bucket (size: 60, refill: 5 per minute)

Path Parameters

Property Type Description
reqId UUID The request identification

QueryString Parameters

Property Type Description
keepResult Boolean Default to false. If true, the optimization is cancelled but current result (if available) is provided as optimization result, this could be not the best possible result for the provided input.

Return Value

[Empty Response Body]

Multi-Day Optimization API

Optimization spread on multiple execution days.

Compute Multi-Day Optimization


curl -X POST https://wwre.workwave.com/opt/v5/optimization/multiday?key=AUTH_KEY \
    "Content-Type: application/json" \
    -d "@request.json"
curl -X POST https://wwre.workwave.com/opt/v5/optimization/multiday/id/551?key=AUTH_KEY \
     "Content-Type: application/json" \
     -d "@request.json"
curl -X POST https://wwre.workwave.com/opt/v5/optimization/multiday/name/myMtx?key=AUTH_KEY \
     "Content-Type: application/json" \
     -d "@request.json"

Where request.json is a file containing the JSON data to be posted
POST https://wwre.workwave.com/opt/v5/optimization/multiday HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com
Content-Type: application/json
POST https://wwre.workwave.com/opt/v5/optimization/multiday/id/551?key=AUTH_KEY HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com
Content-Type: application/json
POST https://wwre.workwave.com/opt/v5/optimization/multiday/name/myMtx?key=AUTH_KEY HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com
Content-Type: application/json
{
  "vehicles": [
    {
      "name": "Vehicle A",
      "origin": {
        "latitude": 42.35516,
        "longitude": -71.76032
      },
      "timeCostModel": {
        "drivingTimeCostFactor": 5000,
        "serviceTimeCostFactor": 5000,
        "idleTimeCostFactor": 5000,
        "breakTimeCostFactor": 5000
      },
      "distanceCostFactor": 100,
      "timeWindow": {
        "startTimeSec": 40000,
        "stopTimeSec": 80000
      },
      "destination": {
        "latitude": 42.35516,
        "longitude": -71.76032
      }
    }
  ],
  "waypoints": [
    {
      "name": "wp 1",
      "location": {
        "latitude": 42.38246,
        "longitude": -71.33345
      },
      "serviceTimeSec": 900
    },
    {
      "name": "wp 2",
      "location": {
        "latitude": 42.4559,
        "longitude": -71.52353
      }
    },
    {
      "name": "wp 3",
      "location": {
        "latitude": 42.53996,
        "longitude": -71.41965
      }
    }
  ]
}

The above command returns JSON structured like this:

Asynchronous response

{
  "reqID": "4e0e9137-8dc5-42ff-aa83-23e1865aeca2",
  "status": "PROCESSING",
  "progress": 33,
  "resultAvailable": false,
  "queuePosition": 0
}

Synchronous response

{
  "reqID": "dd0ef471-6223-427b-9017-ffc6dd4688a1",
  "status": "COMPLETED",
  "matrixID": -1,
  "elapsedSec": 0,
  "routes": [
    {
      "vehicle": {
        "number": 0,
        "name": "Vehicle A"
      },
      "routeStats": {
        "breakTimeSec": 0,
        "driveTimeSec": 9495,
        "idleTimeSec": 0,
        "serviceTimeSec": 900,
        "workTimeSec": 10395,
        "distanceMt": 135736,
        "perStopSetupTimeSec": 0,
        "perStopSetupCost": 0,
        "clusterSetupTimeSec": 0,
        "clusterEnterTimeSec": 0,
        "clusterExitTimeSec": 0,
        "clusterEnterCost": 0,
        "clusterExitCost": 0
      },
      "cost": 65548600,
      "steps": [
        {
          "stepNumber": 0,
          "waypoint": {
            "name": "origin",
            "number": -1
          },
          "latitude": 42.35516,
          "longitude": -71.76032,
          "timeWindow": {
            "startTimeSec": 40000,
            "stopTimeSec": 80000
          },
          "arrivalTimeSec": 0,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 0,
          "departureTimeSec": 40000,
          "nextStepDriveTimeSec": 2693,
          "nextStepDistanceMt": 52553,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 0,
            "idleTimeSec": 0,
            "serviceTimeSec": 0,
            "workTimeSec": 0,
            "distanceMt": 0,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        },
        {
          "stepNumber": 1,
          "waypoint": {
            "name": "wp 3",
            "number": 2
          },
          "latitude": 42.53996,
          "longitude": -71.41965,
          "arrivalTimeSec": 42693,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 42693,
          "departureTimeSec": 42693,
          "nextStepDriveTimeSec": 2436,
          "nextStepDistanceMt": 26830,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 2693,
            "idleTimeSec": 0,
            "serviceTimeSec": 0,
            "workTimeSec": 2693,
            "distanceMt": 52553,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        },
        {
          "stepNumber": 2,
          "waypoint": {
            "name": "wp 1",
            "number": 0
          },
          "latitude": 42.38246,
          "longitude": -71.33345,
          "arrivalTimeSec": 45129,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 45129,
          "departureTimeSec": 46029,
          "nextStepDriveTimeSec": 2447,
          "nextStepDistanceMt": 22595,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 5129,
            "idleTimeSec": 0,
            "serviceTimeSec": 900,
            "workTimeSec": 6029,
            "distanceMt": 79383,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        },
        {
          "stepNumber": 3,
          "waypoint": {
            "name": "wp 2",
            "number": 1
          },
          "latitude": 42.4559,
          "longitude": -71.52353,
          "arrivalTimeSec": 48476,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 48476,
          "departureTimeSec": 48476,
          "nextStepDriveTimeSec": 1919,
          "nextStepDistanceMt": 33758,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 7576,
            "idleTimeSec": 0,
            "serviceTimeSec": 900,
            "workTimeSec": 8476,
            "distanceMt": 101978,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        },
        {
          "stepNumber": 4,
          "waypoint": {
            "name": "destination",
            "number": -2
          },
          "latitude": 42.35516,
          "longitude": -71.76032,
          "arrivalTimeSec": 50395,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 0,
          "departureTimeSec": 50395,
          "nextStepDriveTimeSec": 0,
          "nextStepDistanceMt": 0,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 9495,
            "idleTimeSec": 0,
            "serviceTimeSec": 900,
            "workTimeSec": 10395,
            "distanceMt": 135736,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        }
      ]
    }
  ],
  "unreachedWaypoints": [],
  "unreachableWaypoints": [],
  "unneededVehicles": [],
  "warnings": []
}

Perform a multi day optimization request, that can refers or not a pre-generated matrix. If a request do not use a matrix (so called one-shot request), a distance/time matrix will be computed and, at the end of computation, deleted.

HTTP Request

One-Shot HTTP Request

POST https://wwre.workwave.com/opt/v5/optimization/multiday

Matrix Based HTTP Request

A matrix can be referred by name or matrix identification:

Execution Type

Throttling

Leaky bucket (size: 60, refill: 5 per minute)

Path Parameters

Property Type Description
matrixId Integer Optional. The matrix identification, mutually exclusive with matrixName
matrixName String Optional. The matrix name, mutually exclusive with matrixId

Request Body

MultiDayOptimizationRequest (Request example)

Return Value (synchronous)

MultiDayOptimizationResponse (Response example)

Return Value (asynchronous)

AsyncOptimizationResponse

Get Multi-Day Optimization

curl https://wwre.workwave.com/opt/v5/optimization/multiday/96cb6dcb-3841-489a-bbdc-b95460290362?key=AUTH_KEY
GET https://wwre.workwave.com/opt/v5/optimization/multiday/96cb6dcb-3841-489a-bbdc-b95460290362 HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com

The above command returns JSON structured like this:

Optimization not yet compleated response

{
  "reqID": "96cb6dcb-3841-489a-bbdc-b95460290362",
  "status": "PROCESSING",
  "progress": 33,
  "resultAvailable": false,
  "queuePosition": 0
}

Optimization compleated response

{
  "reqID": "96cb6dcb-3841-489a-bbdc-b95460290362",
  "status": "COMPLETED",
  "matrixID": -1,
  "elapsedSec": 1,
  "routes": [
    {
      "vehicle": {
        "number": 0,
        "name": "Vehicle A"
      },
      "routeStats": {
        "breakTimeSec": 0,
        "driveTimeSec": 9495,
        "idleTimeSec": 0,
        "serviceTimeSec": 900,
        "workTimeSec": 10395,
        "distanceMt": 135736,
        "perStopSetupTimeSec": 0,
        "perStopSetupCost": 0,
        "clusterSetupTimeSec": 0,
        "clusterEnterTimeSec": 0,
        "clusterExitTimeSec": 0,
        "clusterEnterCost": 0,
        "clusterExitCost": 0
      },
      "cost": 65548600,
      "steps": [
        {
          "stepNumber": 0,
          "waypoint": {
            "name": "origin",
            "number": -1
          },
          "latitude": 42.35516,
          "longitude": -71.76032,
          "timeWindow": {
            "startTimeSec": 40000,
            "stopTimeSec": 80000
          },
          "arrivalTimeSec": 0,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 0,
          "departureTimeSec": 40000,
          "nextStepDriveTimeSec": 2693,
          "nextStepDistanceMt": 52553,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 0,
            "idleTimeSec": 0,
            "serviceTimeSec": 0,
            "workTimeSec": 0,
            "distanceMt": 0,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        },
        {
          "stepNumber": 1,
          "waypoint": {
            "name": "wp 3",
            "number": 2
          },
          "latitude": 42.53996,
          "longitude": -71.41965,
          "arrivalTimeSec": 42693,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 42693,
          "departureTimeSec": 42693,
          "nextStepDriveTimeSec": 2436,
          "nextStepDistanceMt": 26830,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 2693,
            "idleTimeSec": 0,
            "serviceTimeSec": 0,
            "workTimeSec": 2693,
            "distanceMt": 52553,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        },
        {
          "stepNumber": 4,
          "waypoint": {
            "name": "destination",
            "number": -2
          },
          "latitude": 42.35516,
          "longitude": -71.76032,
          "arrivalTimeSec": 50395,
          "idleTimeSec": 0,
          "serviceStartTimeSec": 0,
          "departureTimeSec": 50395,
          "nextStepDriveTimeSec": 0,
          "nextStepDistanceMt": 0,
          "perStopSetupTimeSec": 0,
          "cumulativeRouteStats": {
            "breakTimeSec": 0,
            "driveTimeSec": 9495,
            "idleTimeSec": 0,
            "serviceTimeSec": 900,
            "workTimeSec": 10395,
            "distanceMt": 135736,
            "perStopSetupTimeSec": 0,
            "perStopSetupCost": 0,
            "clusterSetupTimeSec": 0,
            "clusterEnterTimeSec": 0,
            "clusterExitTimeSec": 0,
            "clusterEnterCost": 0,
            "clusterExitCost": 0
          },
          "cumulativeCapacityMap": {}
        }
      ]
    }
  ],
  "unreachedWaypoints": [],
  "unreachableWaypoints": [],
  "unneededVehicles": [],
  "warnings": []
}

Return the outcome or the status of a multi-day optimization. The body returned by this invocation is identical to the one that would have been returned by a synchronous invocation, error responses included (in case the optimization failed for some reason).

If the optimization request is asynchronous and is not yet completed, the response is limited to the request identification and the status parameters.

HTTP Request

GET https://wwre.workwave.com/opt/v5/optimization/multiday/:reqId

Execution Type

Synchronous

Throttling

Leaky bucket (size: 60, refill: 5 per minute)

Path Parameters

Property Type Description
reqId UUID The request identification

Return Value

Delete Multi-Day Optimization

curl –X DELETE https://wwre.workwave.com/opt/v5/optimization/multiday/96cb6dcb-3841-489a-bbdc-b95460290362?key=AUTH_KEY
curl –X DELETE https://wwre.workwave.com/opt/v5/optimization/multiday/96cb6dcb-3841-489a-bbdc-b95460290362?key=AUTH_KEY&keepResult=true
DELETE https://wwre.workwave.com/opt/v5/optimization/multiday/96cb6dcb-3841-489a-bbdc-b95460290362 HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com
DELETE https://wwre.workwave.com/opt/v5/optimization/multiday/96cb6dcb-3841-489a-bbdc-b95460290362?keepResult=true HTTP/1.1
Accept: application/json
X-WorkWave-Key: AUTH_KEY
Host: wwre.workwave.com

If the request is already completed or canceled

{
  "errorCode": -1102,
  "errorDescription": "Can't abort request with ID [96cb6dcb-3841-489a-bbdc-b95460290362] that has already been completed"
}

Cancel an asynchronous multi-day optimization request.

If the request is queued will be removed from the queue, if the request is already completed or canceled a cancel command will be ignored (caller will be informed with a warning message), while if the request is processing will be forcefully terminated.

HTTP Request

DELETE https://wwre.workwave.com/opt/v5/optimization/multiday/:reqId[?keepResult=<Boolean>]

Execution Type

Synchronous

Throttling

Leaky bucket (size: 60, refill: 5 per minute)

Path Parameters

Property Type Description
reqId UUID The request identification

QueryString Parameters

Property Type Description
keepResult Boolean Default to false. If true, the optimization is cancelled but current result (if available) is provided as optimization result, this could be not the best possible result for the provided input.

Return Value

[Empty Response Body]

Object Definitions

Matrix

Matrix Object

Property Type Description
id Integer Matrix identification
name String Matrix name assigned during creation
creationDate Long Creation date in milliseconds (Unix Epoch)

Single Day Optimization

Single Day Optimization Request Object

Property Type Description
vehicles List of Vehicle Mandatory. List of objects defining vehicle properties like costs, working time window and capacity
waypoints List of Waypoint Mandatory. List of objects defining waypoint properties like latitude, longitude and delivery time window
altWaypointsGroups List of List of Waypoint Defines groups of alternative Waypoints.

After the main optimization completes, and for each defined group of waypoints, an additional progressive optimization is performed after replacing the original waypoints with those in the alternative group (which is typically smaller than the original set). Each alternative waypoint object must define a "refNumber" property, setting it to the 0-based index of the waypoint in the "waypoints" list to replace.

Results of the additional optimizations are stored separately from the main optimization result in the response property "altResults".

Typical usage scenario: best-fit and next-best-fit simulations: compute multiple results testing the impact of having one single waypoint (or a small subset) served at different time windows and/or by different vehicles (via tag constraints). In this scenario altWaypointGroups would contain several 1-waypoint alternatives
async Boolean Defaults to false. Determine if this request should be blocking or asynchronous
balanced Boolean Default to true. Set to true to balance route duration, set to false to disable route duration balancing and minimize the overall duration of all routes
callbackUrl URL URL to be notified about the completion of the optimization request.
When the optimization completes an HTTP GET request is sent from the Routing Engine server to the specified URL, adding a "reqID" and a "success" GET parameters.

For example, if callbackUrl is http://my.server.com/webhooks/opt?myID=1234

The request will be sent as: http://my.server.com/webhooks/opt?myID=1234&success=[true|false]&reqID=[uuid]

The remote server is expected to accept the TCP connection and return an HTTP 200 OK code within 15 seconds. Failing that, the callbackUrl is invoked again up to 10 times according to the following retry strategy:
  • 1st invocation: immediately after the optimization completes (successfully or not)
  • subsequent invocations: after (#retries * 20) seconds
clustering Clustering Defines routing behavior on predefined waypoint clusters.
Clusters are defined based on the "clusters" property set on Waypoint.
optimization OptimizationParameters Parameters that affects the behaviour of the optimization algorithm
routeHints List of RouteHint Defines a list of routes that are used as the starting point for further optimization.

Route hints derived from a previous optimization request and used to "bootstrap" a further similar optimization (e.g.: one including additional waypoints that need to be "fit in"), can provide a major boost in terms of response time.

IMPORTANT: Route hints are checked for errors and for constraint violations. Invalid routes are partially or fully dropped.

IMPORTANT: Providing low-quality, partial, irrelevant or invalid route hints may lead to sub-optimal results with respect to the same request submitted without route hints
routings map[String]RoutingParameters Specific parameters for the routing module
traffic Traffic Defines traffic patterns

Single Day Optimization Response Object

Property Type Description
reqID UUID Globally unique request ID. Can be used with the "export" resource to get a link to a map showing the optimized routes
matrixID Integer ID of the Matrix.

-1 for one-shot optimizations that do not used a saved matrix
elapsedSec Integer Duration of the optimization process in seconds
status String One of:
  • QUEUED
  • PROCESSING
  • COMPLETED

QUEUED and PROCESSING statuses only apply to asynchronous requests
routes List of Route List of computed routes, one for each used vehicle
unreachableWaypoints List of OutWaypoint List of OutWaypoint objects defining the waypoints that cannot be served in any feasible solution. A waypoint belongs to this list if no vehicle can serve it, even if it is the only waypoint served by the vehicles (e.g. waypoint requires a tag that no vehicle has).
Each element represents the name of a waypoint as provided in the input (or an empty string if not provided)
unreachedWaypoints List of OutWaypoint List of OutWaypoint objects defining the waypoints that, with the given constraints, could not be reached/served.
Is the difference between the waypoints in input and those in output that are not associated with any route.
There are two consideration:
  • {unreachableWaypoints} set is included in the {unreachedWaypoints} set, because each "unreachable" waypoint is a waypoint that can't be served
  • the difference between the two sets "{unreachedWaypoints} - {unreachableWaypoints}" is the set with those waypoints that you could serve if you had enough resources (i.e. more vehicles)
unneededVehicles List of OutVehicle List of OutVehicle objects defining the unneeded vehicles
warnings List of CodedMessage List of warnings defined by a numeric code and a descriptive message. Warnings are issued when, for example, the optimization request completes successfully but some geodesic distances are used instead of actual driving durations because one or more coordinates cannot be linked to the road network
altResults List of AlternativeResult List of optimization results performed on the alternative set of waypoints

Multi Day Optimization

Multi Day Optimization Request Object

Basic format of a multi day request

{
  "vehicles": [
    {
      "name": "Vehicle A",
      "daySettings": {
        "1": {
          // settings for day 2020.06.01
        },
        "2": {
          // settings for day 2016.06.02
        },
        "4": {
          // settings for day 2016.06.04
        },
        // ... more days
      }
    },
    {
      "name": "Vehicle B",
      "daySettings": {
        "1": {
          // settings for day 2016.06.01
        },
        "2": {
          // settings for day 2016.06.02
        },
        // ... more days
      }
    },
    // ... more vehicles
  ],
  "waypoints": [
    {
      "name": "Waypoint #1",
      "eligibleDays" : [1, 2],
      // ... more waypoint constraints
    },
    // ... more waypoints
  ]
}
Property Type Description
vehicles List of MultiDayVehicle Mandatory. List of objects defining vehicle properties like costs, working time window and capacity
waypoints List of MultiDayWaypoint Mandatory. List of objects defining waypoint properties like latitude, longitude and delivery time window
altWaypointsGroups List of List of MultiDayWaypoint Defines groups of alternative Waypoints.

After the main optimization completes, and for each defined group of waypoints, an additional progressive optimization is performed after replacing the original waypoints with those in the alternative group (which is typically smaller than the original set).

Each alternative waypoint object must define a "refNumber" property, setting it to the 0-based index of the waypoint in the "waypoints" array to replace.

Results of the additional optimizations are stored separately from the main optimization result in the response property "altResults".

Typical usage scenario: best-fit and next-best-fit simulations: compute multiple results testing the impact of having one single waypoint (or a small subset) served at different time windows and/or by different vehicles (via tag constraints). In this scenario altWaypointGroups would contain several 1-waypoint alternatives
async Boolean Defaul to false. Determine if this request should be blocking or asynchronous
balanced Boolean Default to true. Set to true to balance route duration, set to false to disable route duration balancing and minimize the overall duration of all routes
callbackUrl URL URL to be notified about the completion of the optimization request.
When the optimization completes an HTTP GET request is sent from the Routing Engine server to the specified URL, adding a "reqID" and a "success" GET parameters.

For example, if callbackUrl is http://my.server.com/webhooks/opt?myID=1234

The request will be sent as: http://my.server.com/webhooks/opt?myID=1234&success=[true|false]&reqID=[uuid]

The remote server is expected to accept the TCP connection and return an HTTP 200 OK code within 15 seconds. Failing that, the callbackUrl is invoked again up to 10 times according to the following retry strategy:
  • 1st invocation: immediately after the optimization completes (successfully or not)
  • subsequent invocations: after (#retries * 20) seconds
clustering Clustering Defines routing behavior on predefined waypoint clusters.

Clusters are defined based on the "cluster" property set on Waypoint objects
optimization OptimizationParameters Parameters that affects the behaviour of the optimization algorithm
routeHints List of MultiDayRouteHint If specified, defines a list of routes that are used as the starting point for further optimization.

Route hints derived from a previous optimization request and used to "bootstrap" a further similar optimization (e.g.: one including additional waypoints that need to be "fit in"), can provide a major boost in terms of response time.

IMPORTANT: Route hints are checked for errors and for constraint violations. Invalid routes are partially or fully dropped.

IMPORTANT: Providing low-quality, partial, irrelevant or invalid route hints may lead to sub-optimal results with respect to the same request submitted without route hints
routings map[String]RoutingParameters Specific parameters for the routing module
traffic Traffic Defines traffic patterns

Multi Day Optimization Response Object

Property Type Description
reqID UUID Globally unique request ID.

Can be used with the "export" resource to get a link to a map showing the optimized routes
matrixID Integer ID of the Matrix.

-1 for one-shot optimizations
elapsedSec Integer Duration of the optimization process in seconds
status String One of:
  • QUEUED
  • PROCESSING
  • COMPLETED

QUEUED and PROCESSING statuses only apply to asynchronous requests
routes List of MultiDayRoute List of computed routes, one for each day and for each vehicle that is used in that day
unreachableWaypoints List of OutWaypoint List of OutWaypoint objects defining the waypoints that cannot be served in any feasible solution. A waypoint belongs to this list if no vehicle can serve it, even if it is the only waypoint served by the vehicles (e.g. waypoint requires a tag that no vehicle has).
Each element represents the name of a waypoint as provided in the input (or an empty string if not provided)
unreachedWaypoints List of OutWaypoint List of OutWaypoint objects defining the waypoints that, with the given constraints, could not be reached/served.
Is the difference between the waypoints in input and those in output that are not associated with any route.
There are two consideration:
  • {unreachableWaypoints} set is included in the {unreachedWaypoints} set, because each "unreachable" waypoint is a waypoint that can't be served
  • the difference between the two sets "{unreachedWaypoints} - {unreachableWaypoints}" is the set with those waypoints that you could serve if you had enough resources (i.e. more vehicles)
unneededVehicles
warnings List of CodedMessage List of warnings defined by a numeric code and a descriptive message. Warnings are issued when, for example, the optimization request completes successfully but some geodesic distances are used instead of actual driving durations because one or more coordinates cannot be linked to the road network
altResults List of MultiDayAlternativeResult List of optimization results performed on the alternative set of waypoints

Async Optimization

Property Type Description
reqID UUID Globally unique request ID
status String One of:
  • QUEUED: request is queued an will be executed soon
  • PROCESSING: request is executing
  • COMPLETED: the request complete successfully
progress Integer The excetion request progress, in the range [0, 100]:
  • [0]: request is queued and still waiting to be process
  • [1-10]: initialization phase (retrieving resources and scheduling sub tasks accross the whole cluster)
  • [11-50]: time and distance matrices computation
  • [51-90]: routing solver execution phase
  • [91-99]: stage for finalizing request resources (releasing resources, save and cache result)
  • [100]: request is completed and result is available
resultAvailable Boolean true if a partial result is available, false if a partial result is not
queuePosition Integer The queue position, in the assigned server, of this request respect to all requests made by the same key and currently in QUEUED status

Routing

Routing Request Object

Property Type Description
sequences List of RoutingSequence Mandatory. One or more sequences of ordered waypoints
addDrivingDirection Boolean Default to false. If set to true add to the response the “directions” field with the driving directions
includeOriginalWPCoords Boolean Defaul to false. If true the returned polylines should start and end at the original waypoint coordinates, even if they are not curb coordinates.

Scenario: the input coordinates might be rooftop ones. If includeOriginalWPCoords is true than the polyline will start at the house, go in a straight line fashion to the curb coordinate where the actual polyline starts and proceed from there with the same logic being applied for the end coordinates. If includeOriginalWPCoords is false the polyline will "get close" to the input coordinates but without "touching" them and traveling exclusively on the road network
routings map[String]RoutingParameters Specific parameters for the routing module

Routing Response Object

Property Type Description
routes List of RoutingRoute A route object for each segment in the request

Miscellaneous Objects

Vehicle Object

Property Type Description
name String Mandatory. Unique vehicle identifier.

Note: The following substrings/characters are NOT allowed: '..', '/', '\', '&', '?', '#', '='
origin Location Mandatory. The location of the start point for this vehicle.
activationCost Integer Defaul to 0. A cost, in terms of "seconds of working time", that is factored-in internally if the vehicle is used. Cannot be a negative value (activationCost >= 0).

Usage example: In a multi-vehicle optimization where all waypoints can be served by a subset of vehicles (excess of resources), the optimization logic will prefer vehicles with a lower activationCost.

Note: the value of this parameter does not modify the returned scheduled times, it is only considered internally by the optimization logic to determine whether to use the vehicle or not.

Note: this parameter is only relevant in multi-vehicle optimizations.
breaks List of Break Breaks defined for this vehicle.

If multiple Breaks are specified, they must be non-overlapping.

If a Time Window is specified for this vehicle then all defined breaks must be fully contained in the Time Window (i.e.: break's startTimeSec > timewindow's startTimeSec AND break's stopTimeSec + durationSec < timewindow's stopTimeSec).

This parameter can’t be set if the dynamicBreaks parameter is defined too.
destination Location If provided, defines the location of the end-destination for this vehicle. If not specified, the route calculated for this vehicle terminates with the last visited waypoint
destinationClusters List of String The name of clusters associated with the destination depot of the vehicle
distanceCostFactor Double Default to 0.0. A multiplicative factor applied internally to the distance traveled by the vehicle. Must be non-negative (distanceCostFactor >= 0).

Usage examples: By increasing the distanceCostFactor the optimization logic will be forced towards solutions in which waypoints that are geographically near are served consecutively even if this implies an increase in overall working time (this happens, as example, when two near waypoints have very different time windows).
dynamicBreaks List of DynamicBreak List of dynamic breaks defined for this vehicles.

It’s the solver that find the best (minimizing the whole route cost) allocation for each break. This parameter can’t be set if the breaks parameter is defined too.
forceUse Boolean Default to false. It must be used just with the minimum requirements feature like minWorkingTimeSec and minCapacityMap. If true, force to use the vehicle even if it is not used by the optimizer for contrains on minimum requirements, this could result in an increased cost
includeRegion List of Location A list of Locations (from 3 up to 50, different and non-collinear) specifying the shell of a simple closed polygon. Concave, convex and self-intersecting polygons are supported. If specified, only this vehicle will be allowed to serve waypoints falling inside the defined region (including edges).

Note: all other constraints still apply (if, for example, a waypoint included in this vehicle’s region requires a tag defined by a different vehicle, that waypoint will not be served).

Note: a vehicle defining an includeRegion is still allowed to serve other waypoints not included in its region.

Note: defining a region does not make included waypoints more likely to be served than others nor does it force the vehicle to serve them before other waypoints. It just prevents them from being served by other vehicles (unless they are also included in overlapping regions defined by those other vehicles).
maxCapacityMap map[String]Integer List of maximum capacities for the vehicle. Each capacity is identified by a user-defined name (e.g.: "weight", "pounds", "seats", "volume_cm3", "crates", etc) and an integer value representing the maximum allowed capacity
maxDistanceMt Integer Maxium allowed distance (meters) from departure to arrival at the end destination
maxDrivingTimeSec Integer Maximum allowed driving time from departure to arrival at the end destination. If not set or set to 0, the maximum driving time is limited by the timeWindow (or not limited at all if no timeWindow was specified). If specified together with maxWorkingTimeSec, then both constraints are enforced
maxOrders Integer Maxium number or orders that can be assigned to this vehicle
maxWorkingTimeSec Integer Maximum allowed working time from departure to arrival at the end destination. "Working time" is the driving time + service time at each served waypoint + break time (if any). If not set or set to 0, the maximum working time is limited by the timeWindow (or not limited at all if no timeWindow was specified)
minCapacityMap map[String]Integer List of minimum capacities for the vehicle. Each capacity is identified by a user-defined name (e.g.: "weight", "pounds", "seats", "volume_cm3", "crates", etc) and an integer value representing the minimum capacity.

It is not an "hard constraints" but just a "best effort", meaning that it can be violated if by doing so results if better optimization results (i.e.: less costly solution)
minWorkingTimeSec Integer Minimum working time from departure to arrival.

Is not an "hard constraints" but is a "best effort", meaning that it can be violated if by doing so results if better optimization results (i.e.: less costly solution)
originClusters List of String The name of clusters associated with the origin depot of the vehicle
overdistanceStartMt Integer Meter after which the default distance cost factor (see distanceCostFactor above) is replaced by the over distance cost factor (see overdistanceCostFactor)
overdistanceCostFactor Double Default to 0.0. A multiplicative factor applied internally to the kilometers traveled by the vehicle after the first overdistanceStartMt meters
overtimeCostModel TimeCostModel Cost model for the time consumed by the vehicle during overtime
overtimeStartTimeSec Integer Time after which the default time cost model (above) is replaced by the overtime cost model (below)
perStopCost Integer Default to 0. A cost that is factored-in internally every time the vehicle stops at a waypoint belonging to a different cluster along its route.

NOTE: If none of the waypoints define the "cluster" property, waypoints are automatically clustered based on proximity, namely: waypoints that share the same location are considered part of the same cluster (i.e.: "perStopCost" is incurred only once when consecutively servicing multiple waypoints sharing the same location, multiple times if the waypoints' locations are different).
perStopSetupTimeSec Integer Defaul to 0. The setup time in seconds incurred every time the vehicle has to stop at a different location along its route (e.g.: parking time, per-stop equipment setup time, etc)
schedulingMode String Defaul to "FLEX_DEPARTURE". Used for selecting the mode that should be used for scheduling the vehicle.

Allowed values are:
  • FLEX_DEPARTURE: optimization engine chooses the departure time (within the given time window) that minimizes the overall working time.
  • FIXED_DEPARTURE: the optimization engine forces the vehicle to depart at the beginning of the working time window. This leads to routes that, on average, are completed earlier but with a potentially longer working time.

For example: given a working Time Window between 8am and 6pm, with schedulingMode set to FLEX_DEPARTURE the output schedule could be 9am-5pm. While if we use FIXED_DEPARTURE the output schedule could be 8am-4.30pm.

Note: this parameter is only relevant when, in an optimization, the visited waypoints have time window constraints or the vehicle define one or more breaks.
speedFactor Double Defaul to 1.0. Vehicle's specific speed multiplier.

Typically used in multi-vehicle optimizations when different vehicles have different average speeds. Allowed range is 0.2-4.0, out of range values are capped at range bounds. See also the global baseTrafficFactor parameter.
tags List of String List of textual tags associated to this vehicle.

Used together with waypoint's tagsExclude, tagsIncludeAnd and tagsIncludeOr fields, tags enable configuring complex vehicle-to-waypoint association constraints.
timeCostModel TimeCostModel The cost model for the time consumed by the vehicle
timeWindow TimeWindow If provided, defines the vehicle availability time range. If not specified, the vehicle will always be considered as available.

The vehicle's time window will take into account the service time at the last visited waypoint and, if a destination is specified, the driving time to get there (that is, this API will never schedule a route so that the scheduled time of arrival at the last waypoint + the service time at that waypoint + the driving time to reach the destination exceeds the vehicle's time window).

Note: both start time and stop time of this time window must be in the single day interval [0s, 86400s]
trafficProfile String The name of the traffic profile used by this vehicle

Break Object

Property Type Description
durationSec Integer Mandatory. Break duration in seconds.
The break can be scheduled to start at any time between startTimeSec and stopTimeSec, and lasts for durationSec.
startTimeSec Integer Mandatory. Minimum allowed break start time in seconds since midnight (00:00).
The allowed range can span a maximum of a 7-days period [0 – 604800]
stopTimeSec Integer Mandatory. Maximum allowed break stop time in seconds since midnight (00:00).
Must be >= startTimeSec. The allowed range can span a maximum of a 7-days period [0 – 604800]

Example: startTimeSec = 43200 (12:00), stopTimeSec = 45000 (12:30) and durationSec = 3600 (1 hour) means: schedule a 1-hour break starting at any time between 12:00 and 12:30.

Waypoint Object

Property Type Description
location Location Mandatory. Defines waypoint latitude/longitude coordinates
clusters List of String The name of clusters associated with the waypoint.

Note: if a waypoint is associated with a park & walk cluster, its name shouldn’t be inserted in this array (see the following parkAndWalkCluster parameter)
deliveryMap map[String]Integer Defines the size of the delivery in terms of load unit types (i.e.: consumed vehicle capacity).
Mutually exclusive with pickupMap (each waypoint is either a delivery or a pickup, not both). 0 where not specified
dropoffNumber Integer When defined marks this waypoint as a "pickup for dropoff".

The value represents the zero-based index of the dropoff waypoint in the "waypoints" array.

A waypoint defining a dropoffNumber is a pickup point and therefore its deliveryMap must be empty. Consequently, the referenced dropoff waypoint is a dropoff/delivery point and therefore its pickupMap must be empty
name String If provided, this name string can be used to identify this waypoint in the output
pickupMap map[String]Integer Defines the size of the pickup in terms of load unit types (i.e.: consumed vehicle capacity).
Mutually exclusive with deliveryMap (each waypoint is either a delivery or a pickup, not both). 0 where not specified
parkAndWalkCluster String Park & walk cluster associated with the waypoint
priority Integer Default to 0. Defines the priority of this waypoint where 0 is the lowest possible priority

Note: Priority is only taken into account when all Waypoints cannot be serviced by the given Vehicles: under such circumstances Waypoints with a higher priority are preferred over lower-priority ones.
refNumber Integer References the waypoint that will be replaced by this one when processing alternative waypoint groups.

Mandatory for waypoints defined as part of an alternative waypoint group, ignored otherwise. The value represents the zero-based index of the referenced waypoint in the Waypoint list.
serviceTimeSec Integer The default amount of time in seconds which a vehicle is expected to be stationary at this waypoint (i.e. the time required for the servicing to take place).

0 where not specified
serviceTimeSecPerVehicle map[Integer]Integer Override the default service time for the specified vehicles. Each map pair is defined by the index (the map key) of the vehicle in the zero-indexed list "vehicles" and by the ad-hoc service time for the specified vehicle (the map value).

This enables modeling scenarios where the time it takes to serve a waypoint can be different based on what vehicle actually serves it.

Examples are landscaping scenarios where a vehicle carring a team of 4 techs can serve a waypoint in half the time it would take a vehicle with only 2 techs on board: vehicle Ve1, with only 1 tech on board, takes 20 mins to serve waypoint A while vehicle Ve2, with 3 techs on board, takes 7 mins to serve the same waypoint
tagsExclude List of String Define tag-based vehicle exclusion constraints: all vehicles defining one or more tags in this list are not allowed to service this waypoint.

Exclusion constraints take precedence over inclusion ones
tagsIncludeAnd List of String Define tag-based vehicle inclusion constraints: only vehicles defining all tags in this list (AND-criteria) are allowed to service this waypoint
tagsIncludeOr List of String Define tag-based vehicle inclusion constraints: all vehicles defining one or more tags in this list (OR-criteria) are allowed to service this waypoint
timeWindows List of TimeWindow If provided, defines an array of arrival time window constraints for this waypoint.

Each time window defines a time interval when the waypoint can start to be serviced. This interval does not include the service time (e.g.: if service time is 30 minutes and the time window is from 10:00 to 11:00, then it is ok for the vehicle to arrive and start servicing the waypoint at 10:59 and complete the service 30 minutes later at 11.29). If the time window must include the service time, just subtract the service time from the end time of the time window (e.g.: if service time is 30 minutes and the time window is from 10:00 to 11:00 and must include the service time, then change the time window to be from 10:00 to 10:30).

Multiple time windows can be used, for example, to prevent the waypoint from being serviced in off-limits intervals (e.g.: defining the time windows: 8:00-12:00 and 14:00-18:00 would prevent the waypoint from being serviced between 12:00 and 14:00).

If not specified, this waypoint will always be available to be serviced

TimeWindow Object

Property Type Description
startTimeSec Integer Mandatory. Default to 0. Time window start time in seconds since midnight (00:00).

The allowed range can span a maximum of a 7-days period [0 – 604800]
stopTimeSec Integer Mandatory. Default to 86400. Time window stop time in seconds since midnight (00:00).

The allowed range can span a maximum of a 7-days period [0 – 604800] and must be >= startTimeSec.

Location Object

Property Type Description
latitude Double Mandatory. Latitude coordinate in decimal format specified using the WGS 84 reference frame (e.g.: 45.397204)
longitude Double Mandatory. Longitude coordinate in decimal format specified using the WGS 84 reference frame (e.g.: 9.251765)

Traffic Object

Property Type Description
trafficProfiles map[String]TrafficProfile Map associating the name of a traffic profile to its definition
trafficTimeWindows List of TimeWindow An array of traffic time-windows.

The given time windows must not overlap.

The maximum number of time windows is currently limited to 2

TrafficProfile Object

Property Type Description
baseTrafficFactor Double Default to 1.0. Global route duration multiplier, ised to take into account a static and global traffic scenario (all driving times for vehicles using this profile are multiplied by baseTrafficFactor, regardless of area and time). Affects all routes.

Allowed range is 0.5-5.0, out of range values are capped at range bounds.

Set to 1.0 for normal traffic conditions.

See also vehicle's speedFactor parameter
trafficRegions List of TrafficRegion If provided, defines an array of regions associated to time-dependent trafficFactors.

Each region’s trafficFactor is proportionally applied to the percentage of each arc intersecting that region.

NOTE: Regions are intended to cover a sufficiently wide area (e.g.: a city, a city center, a borough, a district, a suburban area, etc). Regions that strictly contour specific roads will not work as expected and should be avoided.

NOTE: The maximum number of Locations (aka polygon vertices) that can be specified by all trafficRegions combined is limited to 100.

NOTE: In case of overlapping regions, the region with the highest trafficFactor is considered for the overlapping area (for each defined traffic time-window).

NOTE: the global baseTrafficFactor parameter and trafficRegions can both be specified and are both independently applied. E.g.: Assuming two non-overlapping regions R1 and R2 are defined:

Driving time from A to B: baseTrafficFactor * AB * (1 + AB_%intersecting_R1 * (1 – R1_trafficFactor) + AB%_intersecting_R2 * (1 – R2_trafficFactor))

TrafficRegion Object

Property Type Description
region List of Location Mandatory. A list of 3 or more Locations (different and non-collinear) defining the shell of a simple closed polygon.

Concave and convex polygons are supported; self-intersecting polygons are accepted but are internally converted to their convex hull (see http://en.wikipedia.org/wiki/Convex_hull)
trafficFactor Double Default to 1.0. The region's default (non time-dependent) trafficFactor.

Applies outside of the defined traffic time-windows.Allowed range is 0.5-5.0, out of range values are capped at range bounds.
twTrafficFactors List of Double A list of time-dependent traffic factors that apply to this region.

Allowed range for each value is 0.5-5.0, out of range values are capped at range bounds.

The size of the array must match the size of the trafficTimeWindows array defined on the parent Traffic object.

Each twTrafficFactor in the array will override "trafficFactor" during its traffic time window.

For example, assuming we have two traffic time windows, one between 7am and 10am, and one between 4pm and 7pm and that this region's default trafficFactor is 1.5 and that twTrafficFactors are [2.1, 3.0], then traveling between any two locations within the region will incur in the following time-dependent penalty:
  • before 7am: normal_travel_time * 1.5
  • between 7am and 10am: normal_travel_time * 2.1
  • between 10am and 4pm: normal_travel_time * 1.5
  • between 4pm and 7pm: normal_travel_time * 3.0
  • after 7pm: normal_travel_time * 1.5

TimeCostModel Object

Property Type Description
drivingTimeCostFactor Double Default to 1.0. A multiplicative factor applied internally to the vehicle driving time (the portion of working time in which the vehicle travels from the current waypoint location to the next one).

Must be non-negative (drivingTimeCostFactor >= 0).

Usage examples:
  • By increasing the drivingTimeCostFactor without increasing other cost factors, the optimization logic will be forced towards solutions that minimize the driving time even if this implies an increase in the overall working time.
  • In a multi-vehicle optimization where all vehicles must be used in order to serve all of the waypoints, the optimization logic will try to assign shorter routes to vehicles with a higher drivingTimeCostFactor and longer routes to vehicles with a lower drivingTimeCostFactor.
Note: the value of this parameter does not modify the returned scheduled times, it is only considered internally by the optimization logic to determine the cost of a route
serviceTimeCostFactor Double Default to 1.0. A multiplicative factor applied internally to the vehicle service time (the portion of working time consumed by the vehicle stationary in a location in order to serve a waypoint).

Must be non-negative (serviceTimeCostFactor >= 0).

Usage examples:
  • By increasing the serviceTimeCostFactor without increasing other cost factors, the optimization logic will be forced towards solutions that minimize only the service time even if this implies an increase in the overall working time.
  • In a multi-vehicle optimization where all vehicles must be used in order to serve all of the waypoints, the optimization logic will try to assign waypoints with shorter service times to vehicles with a higher serviceTimeCostFactor and waypoints with longer service times to vehicles with lower serviceTimeCostFactor.


Note: the value of this parameter does not modify the returned scheduled times, it is only considered internally by the optimization logic to determine the cost of a route
idleTimeCostFactor Double Default to 1.0. A multiplicative factor applied internally to the vehicle idle time (the portion of working time consumed by the vehicle waiting the opening of a waypoint time window after its arrival to the waypoint location).

Must be non-negative (idleTimeCostFactor >= 0).

Usage examples: by increasing the idleTimeCostFactor without increasing other cost factors, the optimization logic will be forced towards solutions having a good matching between the arrival time of the vehicle in a waypoint location and the opening of one of the waypoint time windows, even if this implies an overall increase in the working time.

Note: the value of this parameter does not modify the returned scheduled times, it is only considered internally by the optimization logic to determine the cost of a route
breakTimeCostFactor Double Default to 1.0. A multiplicative factor applied internally to the vehicle break time (the portion of working time consumed during vehicle mandatory breaks).

Must be non-negative (breakTimeCostFactor >= 0).

Usage examples: by increasing the breakTimeCostFactor without increasing other cost factors, the optimization logic will be forced towards solutions that avoid mandatory breaks even if this implies an increase in the overall working time.

Note: the value of this parameter does not modify the returned scheduled times, it is only considered internally by the optimization logic to determine the cost of a route

Clustering Object

Property Type Description
clusters map[String]Cluster A map from cluster names to Cluster objects.

Each cluster name must be defined in at least one of the following arrays:
  • "clusters" property of request waypoints
  • "originClusters" or "destinationClusters" of request vehicles
intersectionFunctions ClusterBehavior Defines the way in which multiple clusters impact on solution times and costs
parkAndWalk map[String]ParkAndWalkCluster A map from park & walk cluster names to ParkAndWalkCluster objects. br/>
Each park & walk cluster name must be defined by at least one waypoint

Cluster Object

Property Type Description
enterCost Integer Default to 0. The cost penalty paid by the vehicle before arriving to the first waypoint of a sequence of waypoints that belong to this cluster
enterTimeSec Integer Default to 0. The driving time penalty paid by the vehicle before arriving to the first waypoint of a sequence of waypoints that belong to this cluster
exitCost Integer Default to 0. The cost paid by the vehicle before exiting from the last waypoint of a sequence of waypoints that belong to this cluster
exitTimeSec Integer Default to 0. The driving time penalty paid by the vehicle before exiting from the last waypoint of a sequence of waypoints that belong to this cluster
requireVehicleStop Boolean Default to false. If it’s equal to True the vehicle must stop before entering into a sequence of waypoints that belong to this cluster
setupTimeSec Integer Default to 0. The setup time required to enter in a cluster, each time the vehicle enter in this cluster. It impacts on the service time of the first waypoint of a sequence of waypoints that belong to this cluster

ParkAndWalkCluster Object

Property Type Description
parkingLocation Location Mandatory. The parking location. A vehicle visiting a Park&Walk cluster is supposed to drive to the parking location, and then the driver will walk to the waypoints belonging to the same cluster.

In order to visit a waypoint outside of the current cluster the driver will return, walking, to the parking location and then drive to that waypoint (or, in case that waypoint belongs to a different Park&Walk cluster, to the parking location defined by that different cluster)
routing ParkAndWalkRouting Mandatory. Defines the routing properties to be used within the cluster
parkingTimeSec Integer Default to 0. The estimated time, in seconds, that the driver will spend parking at the parking location

ParkAndWalkRouting Object

Property Type Description
mode String Mandatory. Default to GEODESIC. One of:
  • GEODESIC: times and distances are computed based on as-the-crow-flies distances and the "avgSpeedKmh" average speed
  • ROAD: times and distances are computed on the actual road network using the routing profile defined by "profile"
    avgSpeedKmh Integer Default to 5. Ignored if mode is ROAD. The average walking speed in Km/h
    profile String Default to WALKING. Ignored if mode is GEODESIC, otherwise can be one of:
    • WALKING: uses the pedestrian routing profile template
    • DRIVING: uses the default routing profile templat

    RouteHint Object

    Property Type Description
    vehicleNumber Integer Mandatory. The Vehicle that this route hint applies to.

    The value represents the zero-based index of the vehicle in the "vehicles" array.
    sequence List of Integers Mandatory. The sequence of waypoints that defines the route. The values in the array represent the zero-based index of the sequence waypoints in the "waypoints" array.

    IMPORTANT: if the given sequence is not compatible with the input constraints, steps will be removed from the sequence in no particular order up to the point where either the sequence becomes compatible or it is completely discarded.

    When a step is discarded, so is any "lock" constraint it may have defined

    ClusterBehavior Object

    Property Type Description
    enterCost String Default to SUM. Describe the way in which multiple clusters enter costs (see enterCost member from Cluster object) will be combined (available functions are "SUM", "AVG", "MIN", "MAX").
    enterTime String Default to SUM. Describe the way in which multiple clusters enter times (see enterTimeSec member from Cluster object) will be combined (available functions are "SUM", "AVG", "MIN", "MAX").
    exitCost String Default to SUM. Describe the way in which multiple clusters exit costs (see exitCost member from Cluster object) will be combined (available functions are "SUM", "AVG", "MIN", "MAX").
    exitTime String Default to SUM. Describe the way in which multiple clusters exit times (see exitTimeSec member from Cluster object) will be combined (available functions are "SUM", "AVG", "MIN", "MAX").
    setupTime String Default to SUM. Describe the way in which multiple clusters setup times (see setup time member from Cluster object) will be combined (available functions are "SUM", "AVG", "MIN", "MAX").

    RoutingParameters Object

    Property Type Description
    exceptions List of ExceptionSegment List of segments that could affect route/matrix computation

    ExceptionSegment Object

    Property Type Description
    end Location Mandatory. End point of the segment
    start Location Mandatory. Start point of the segment
    additionalDrivingTimeSec Integer Default to 0. If the computed route accross this segment this is the amount of time that will be added to the route computation. If additionalDrivingTimeSec is different from 0, the malus property will be ignored
    malus Integer Default to 0. A malus value in the range [-10, +10] where +10 is used for blocking the segment, while -10 is used to indicate the preference of using this segment

    OptimizationParameters Object

    Property Type Description
    dynamicBreakPercentageThreshold Integer Default to 0. The maxium threshold percentage that the algorithm can use for setting dynamic breaks.

    This parameter is mutually exclusive with dynamicBreakSecThreshold parameter, they can’t be used both at the same time
    dynamicBreakSecThreshold Integer Default to 0. The maxium threshold in seconds that the algorithm can use for setting dynamic breaks.

    This parameter is mutually exclusive with dynamicBreakPercentageThreshold parameter, they can’t be used both at the same time

    DynamicBreak Object

    Property Type Description
    durationSec Integer Mandatory. Break duration in seconds
    maxTimeFromPrevSec Integer Mandatory. Maximum time from the previous break that the algorithm has to add the dynamic break to the route. If this is the first dynamic break the “maxTimeFromPrevSec” refers to the start time of the vehicle’s time window

    Route Object

    Property Type Description
    vehicle OutVehicle The OutVehicle object representing the vehicle associated with this route
    steps List of RouteStep Ordered list of route steps. Route steps include one origin, one or more waypoints, zero or one destination (route ends at the last visited waypoint if no destination is specified for the vehicle)
    routeStats RouteStats Cost and time statistics related to this route
    cost Double Total cost of the route: sum of total driving cost, total mileage cost, total idle time cost, total break time cost, total service time cost and total enter/exit cluster cost.

    RouteStats Object

    Property Type Description
    workTimeSec Integer Working time.

    computed as arrival time to destination - departure time
    breakTimeSec Integer Time in seconds elapsed during breaks
    driveTimeSec Integer Driving time in seconds. Includes clusterEnterTimeSec, clusterExitTimeSec and perStopSetupTimeSec
    distanceMt Integer Mileage in meters
    serviceTimeSec Integer Service time in seconds (i.e.: sum of all waypoint service times). Includes clusterSetupTimeSec
    idleTimeSec Integer Idle time in seconds (i.e.: sum of all idle times).

    Idle time happens when, as per schedule, the Vehicle arrives early at a waypoint and must wait, idle, for the waypoint's time window to open.

    Idle time is computed according to this formula:

    idleTimeSec = workTimeSec - drivingTimeSec - serviceTimeSec - breakTimeSec
    perStopSetupTimeSec Integer Time in seconds elapsed during vehicle stops
    perStopSetupCost Integer Cost paid related to vehicle stops
    clusterEnterCost Integer Cost paid to enter in clusters
    clusterExitCost Integer Cost paid to exit from clusters
    clusterSetupTimeSec Integer Setup time in seconds spent to setup before entering in clusters
    clusterEnterTimeSec Integer Time in seconds spent to enter in clusters
    clusterExitTimeSec Integer Time in seconds spent to exit from clusters

    RouteStep Object

    Property Type Description
    stepNumber Integer A zero-based counter indicating the step number in this vehicle's route
    waypoint OutWaypoint Identification of the waypoint associated with this step. If this step represents the origin or the destination depot this field assumes particular values
    latitude Double Latitude coordinate specified using the WGS 84 reference frame (e.g.: 45.397204)
    longitude Double Longitude coordinate specified using the WGS 84 reference frame (e.g.: 9.251765)
    timeWindow TimeWindow Delivery time window constraint for this route step (i.e.: the visited Waypoint’s matching time window).
    Set to the Vehicle’s working time window for origins and empty for the end destination
    arrivalTimeSec String Arrival time in seconds since midnight
    idleTimeSec Integer This field is > 0 if the arrival time is earlier than the time window start time (in which case the vehicle has to wait until the time window start time)
    serviceStartTimeSec String Time when the goods are delivered, in seconds since midnight
    departureTimeSec String Departure time in seconds since midnight
    nextStepDriveTimeSec Integer Time in seconds required to reach the next route step. Always set to 0 for the last step
    nextStepDistanceMt Integer Meters between the current and the next route step. Always set to 0 for the last step
    driveBreakTimeSec Integer This field is > 0 if the driving time between the previous step and this step is interrupted by one or more Vehicle-defined Breaks (e.g.: lunch break) and amounts to the sum of the durationSec of all involved Breaks.

    Note that arrivalTimeSec and all related times already take Vehicle Breaks into account.

    This field is omitted if no Vehicle Breaks are defined in the input request
    driveBreaks List of RouteStepBreak Lists all breaks occurring during the driving time between the previous step and this step.

    This field is omitted if no Vehicle Breaks are defined in the input request
    serviceBreakTimeSec Integer This field is > 0 if the service time at this step is interrupted by one or more Vehicle-defined Breaks (e.g.: lunch break) and amounts to the sum of the durationSec of all involved Breaks.

    Note that departureTimeSec already take Vehicle Breaks into account.

    Note that the optimization engine will try to avoid placing Breaks during a service time if at all possible.

    This field is omitted if no Vehicle Breaks are defined in the input request
    serviceBreaks List of RouteStepBreak Lists all breaks interrupting the service time at this step.

    This field is omitted if no Vehicle Breaks are defined in the input request
    cumulativeCapacityMap map[String]Integer Vehicle capacities consumed up to this step
    cumulativeRouteStats RouteStats Cost and time statistics cumulated from route start to this step

    RouteStepBreak Object

    Property Type Description
    breakTimeSec Integer Break start time in seconds since midnight
    durationSec Integer Break duration in seconds

    CodedMessage Object

    Property Type Description
    code Integer Integer code defining this type of message
    message String Message text

    Where code can be of the following:

    code
    Description
    -10000 Unlinkable coordinates. Some coordinates (full list provided in message text) cannot be linked to the road network. Driving times to and from these locations are estimated using geodesic distances, which may lead to less optimal results and less accurate schedules
    -10100 Unreachable coordinates. Some coordinates (full list provided in message text) are linked to restricted roads and cannot be reached. Driving times to these locations are estimated using geodesic distances, which may lead to less optimal results and less accurate schedules

    AlternativeResult Object

    Property Type Description
    routes List of Route List of computed routes, one for each used vehicle
    unreachableWaypoints List of OutWaypoint List of OutWaypoint objects defining the waypoints that cannot be served in any feasible solution. A waypoint belongs to this list if no vehicle can serve it, even if it is the only waypoint served by the vehicles (e.g. waypoint requires a tag that no vehicle has).
    Each element represents the name of a waypoint as provided in the input (or an empty string if not provided)
    unreachedWaypoints List of OutWaypoint List of OutWaypoint objects defining the waypoints that, with the given constraints, could not be reached/served.
    Is the difference between the waypoints in input and those in output that are not associated with any route.
    There are two consideration:
    • {unreachableWaypoints} set is included in the {unreachedWaypoints} set, because each "unreachable" waypoint is a waypoint that can't be served
    • the difference between the two sets "{unreachedWaypoints} - {unreachableWaypoints}" is the set with those waypoints that you could serve if you had enough resources (i.e. more vehicles)
    unneededVehicles List of OutVehicle List of OutVehicle objects defining the unneeded vehicles

    OutWaypoint Object

    Property Type Description
    name String The name of the referenced waypoint in the "waypoints" array. In route steps that are not waypoints like origin and destination it is set to "origin" and "destination" respectively
    number Integer The value represents the zero-based index of the referenced waypoint in the "waypoints" array. In route steps that are not waypoints like origin and destination it is set to -1 and -2 respectively

    OutVehicle Object

    Property Type Description
    name String The name of the referenced vehicle in the "vehicles" array
    number Integer The value represents the zero-based index of the referenced vehicles in the "vehicles" array
    day Integer Always zero (0) for single-day optimizations

    MultiDayVehicle Object

    Property Type Description
    daySettings map[Integer]Vehicle Mandatory. Maps each working day of the vehicle with its settings for that day
    name String Mandatory. Unique vehicle identifier.

    Note: The following substrings/characters are NOT allowed: '..', '/', '\', '&', '?', '#', '='

    MultiDayWaypoint Object

    Property Type Description
    location Location Mandatory. Defines waypoint latitude/longitude coordinates
    clusters List of Strings The name of clusters associated with the waypoint
    dayLengthSec Integer Default value 86400 (seconds in a single day)‬. The day length, for example the duration of a "day" can be artificially increased to fit both a "day" and a "night" shift into each "extended" day Multi day optimization extended day length
    deliveryMap map[String]Integer Defines the size of the delivery in terms of load unit types (i.e.: consumed vehicle capacity).

    Mutually exclusive with pickupMap (each waypoint is either a delivery or a pickup, not both).

    0 where not specified
    dropoffNumber Integer When defined marks this waypoint as a "pickup for dropoff".

    The value represents the zero-based index of the dropoff waypoint in the "waypoints" array.

    A waypoint defining a dropoffNumber is a pickup point and therefore its deliveryMap must be empty. Consequently, the referenced dropoff waypoint is a dropoff/delivery point and therefore its pickupMap must be empty
    eligibleDays List of Integers The index of days in which this waypoint can be served, all the working days
    name String If provided, this name string can be used to identify this waypoint in the output
    pickupMap map[String]Integer Defines the size of the pickup in terms of load unit types (i.e.: consumed vehicle capacity).

    Mutually exclusive with deliveryMap (each waypoint is either a delivery or a pickup, not both).

    0 where not specified
    priority Integer Default to 0. Defines the priority of this waypoint where 0 is the lowest possible priority.

    Note: Priority is only taken into account when all Waypoints cannot be serviced by the given Vehicles: under such circumstances Waypoints with a higher priority are preferred over lower-priority ones
    refNumber Integer References the waypoint that will be replaced by this one when processing alternative waypoint groups.

    Mandatory for waypoints defined as part of an alternative waypoint group, ignored otherwise.

    The value represents the zero-based index of the referenced waypoint in the "waypoints" array
    serviceTimeSec Integer The default amount of time in seconds which a vehicle is expected to be stationary at this waypoint (i.e. the time required for the servicing to take place).

    0 where not specified
    serviceTimeSecPerVehicle map[Integer]Integer Override the default service time for the specified vehicles. Each map pair is defined by the index (the map key) of the vehicle in the zero-indexed list "vehicles" and by the ad-hoc service time for the specified vehicle (the map value).

    This enables modeling scenarios where the time it takes to serve a waypoint can be different based on what vehicle actually serves it.

    Examples are landscaping scenarios where a vehicle carring a team of 4 techs can serve a waypoint in half the time it would take a vehicle with only 2 techs on board: vehicle Ve1, with only 1 tech on board, takes 20 mins to serve waypoint A while vehicle Ve2, with 3 techs on board, takes 7 mins to serve the same waypoint
    tagsExclude List of String Define tag-based vehicle exclusion constraints: all vehicles defining one or more tags in this list are not allowed to service this waypoint.

    Exclusion constraints take precedence over inclusion ones
    tagsIncludeAnd List of String Define tag-based vehicle inclusion constraints: only vehicles defining all tags in this list (AND-criteria) are allowed to service this waypoint
    tagsIncludeOr List of String Define tag-based vehicle inclusion constraints: all vehicles defining one or more tags in this list (OR-criteria) are allowed to service this waypoint
    timeWindows List of TimeWindow If provided, defines an array of arrival time window constraints for this waypoint.

    Each time window defines a time interval when the waypoint can start to be serviced. This interval does not include the service time (e.g.: if service time is 30 minutes and the time window is from 10:00 to 11:00, then it is ok for the vehicle to arrive and start servicing the waypoint at 10:59 and complete the service 30 minutes later at 11.29). If the time window must include the service time, just subtract the service time from the end time of the time window (e.g.: if service time is 30 minutes and the time window is from 10:00 to 11:00 and must include the service time, then change the time window to be from 10:00 to 10:30).

    Multiple time windows can be used, for example, to prevent the waypoint from being serviced in off-limits intervals (e.g.: defining the time windows: 8:00-12:00 and 14:00-18:00 would prevent the waypoint from being serviced between 12:00 and 14:00). Both start time and stop time of all the time window in the array must be in the single day interval [0s, 86400s].

    If not specified, this waypoint will always be available to be serviced

    MultiDayRouteHint Object

    Property Type Description
    day Integer Mandatory. The day to which this hint applies
    sequence List of Integers Mandatory. The sequence of waypoints that defines the route. The values in the array represent the zero-based index of the sequence waypoints in the "waypoints" array.

    IMPORTANT: if the given sequence is not compatible with the input constraints, steps will be removed from the sequence in no particular order up to the point where either the sequence becomes compatible or it is completely discarded.

    When a step is discarded, so is any "lock" constraint it may have defined
    vehicleNumber Integer Mandatory. The Vehicle that this route hint applies to.

    The value represents the zero-based index of the vehicle in the "vehicles" array

    MultiDayRoute Object

    Property Type Description
    vehicle OutMultiDayVehicle The vehicle associated with this route and the day in which the vehicle serves the route
    steps List of RouteStep Ordered list of route steps. Route steps include one origin, one or more waypoints, zero or one destination (route ends at the last visited waypoint if no destination is specified for the vehicle)
    routeStats RouteStats Cost and time statistics related to this route
    cost Double Total cost of the route: sum of total driving cost, total mileage cost, total idle time cost, total break time cost, total service time cost and total enter/exit cluster cost

    MultiDayAlternativeResult Object

    Property Type Description
    routes List of MultiDayRoute List of computed routes, one for each day and for each vehicle that is used in that day
    unreachableWaypoints List of OutWaypoint List of OutWaypoint objects defining the waypoints that cannot be served in any feasible solution. A waypoint belongs to this list if no vehicle can serve it, even if it is the only waypoint served by the vehicles (e.g. waypoint requires a tag that no vehicle has).
    Each element represents the name of a waypoint as provided in the input (or an empty string if not provided)
    unreachedWaypoints List of OutWaypoint List of OutWaypoint objects defining the waypoints that, with the given constraints, could not be reached/served.
    Is the difference between the waypoints in input and those in output that are not associated with any route.
    There are two consideration:
    • {unreachableWaypoints} set is included in the {unreachedWaypoints} set, because each "unreachable" waypoint is a waypoint that can't be served
    • the difference between the two sets "{unreachedWaypoints} - {unreachableWaypoints}" is the set with those waypoints that you could serve if you had enough resources (i.e. more vehicles)
    unneededVehicles

    OutMultiDayVehicle Object

    Property Type Description
    name String The name of the referenced vehicle in the "vehicles" array
    number Integer The value represents the zero-based index of the referenced waypoint in the "vehicles" array
    day Integer The day in which the vehicle is working

    RoutingSequence Object

    Property Type Description
    sequence List of Location Mandatory. A list of ordered geographical locations

    RoutingRoute Object

    Property Type Description
    legs RoutingLeg Each leg in the response is a polyline and/or the driving directions from a waypoint to the next one in the request
    stats RoutingRouteStats Distance (meters) and time (seconds) computed for a leg.

    If “addNetworkClassesBreakdown” in the request is true you will have the break down statistics for each of 8 network classes (take a look of “Customizable speed profile”)

    RoutingLeg Object

    Property Type Description
    poly String The encoded polyline with the same Google algorithm used for encoding polylines on Google Maps (https://developers.google.com/maps/documentation/utilities/polylinealgorithm).

    Use the polyline encoder utility (https://developers.google.com/maps/documentation/utilities/polylineutility) to draw the polylines in google maps: put the value from field “poly” into the utility at the “Encoded Polyline” text area and then click on the “Decode Polyline” button
    status Integer Three possible values [0, 1, 2]:
    • “0” if the polyline leg has been computed without errors
    • “1” if an error occurs so we fallback to the pedestrian routing profile
    • “2” if the pedestrian routing fails (e.g. a waypoint in a island without connection to the mainland) the encoded polyline is the straight line between the two points
    directions List of RoutingManouvre Driving directions for a leg

    RoutingRouteStats Object

    Property Type Description
    distanceMt Integer Estimated distance (meters).
    timeSec Integer Required travel time (seconds).

    RoutingManouvre Object

    Property Type Description
    type String The manouvre type, one of the following value:
    • TURN_AROUND
    • ROUND_ABOUT
    • SLIGHT_LEFT
    • LEFT
    • SHARP_LEFT
    • SLIGHT_RIGHT
    • RIGHT
    • SHARP_RIGHT
    • STRAIGHT
    • DESTINATION_REACHED
    • WAYPOINT_REACHED
    • ROUTING_ERROR
    • UNKNOWN
    String msg String The driving direction message
    distanceMt Integer Manouvre length (meters)
    timeSec Integer Manouvre requireq time (seconds)