Routing with Multi-day Routes

A multiday-route is a route that spans multiple days with overnight stays each night. See Routing with Dates for information on building routes for more than one day. Multi-day routes are more efficient when jobs are distant from the route start/end location, as the driver can stay overnight at the remote location instead driving back to the depot each night.

Note

To run the examples in this tutorial, you will need:

A RouteCloud API login. Use your Verizon Connect Enterprise username and password to authenticate with the RouteCloud API. To obtain a username and password, contact Verizon Connect sales.
cURL to run the requests. You can download a cURL binary from here.

Overview

A multi-day route is represented as a number of individual routes, linked by overnight stays. The first route starts with a depot stop and ends with an overnight stay. The last route starts with an overnight stay and ends with a depot stop. Any intermediate routes start and end with overnight stays. The previous_multiday_day and next_multiday_day fields are also set to represent the multi-day route links.

Using Multi-day Routes

Enable multi-day routes by assigning a driver to each route via route.driver, and setting driver.max_multiday_days or settings.defaults.max_multiday_days to a value greater than 1. This allows the driver to have routes spanning across multiple days, up to the limit specified by driver.max_multiday_days.

If efficient, the build call will generate multi-day routes. The other calls (sequence, recommend, evaluate) will neither create nor destroy overnight stays. Instead the overnight stay sequence must be input by setting route.has_next_multiday_day to true on any routes that end with an overnight stay. The build call ignores the route.has_next_multiday_day setting as it places overnight stays wherever they are optimal.

Load Capacity and Multi-day Routes

As the driver does not return to the depot for the length of the multi-day route, their job.load accumulates across all days of the multi-day route. The build will never generate a multi-day route where the total accumulated load exceeds the set route.load_capacity.

Build Example

Build Request

{
  "routes": [
    {
      "id": "route0",
      "location": "39.730489,-104.989109",
      "date": "2016-03-14",
      "driver": "driver0",
      "start_time": "09:00",
      "max_working_time": "08:00"
    },
    {
      "id": "route1",
      "location": "39.730489,-104.989109",
      "date": "2016-03-15",
      "driver": "driver0",
      "start_time": "09:00",
      "max_working_time": "08:00"
    },
    {
      "id": "route2",
      "location": "39.730489,-104.989109",
      "date": "2016-03-16",
      "driver": "driver0",
      "start_time": "09:00",
      "max_working_time": "08:00"
    }
  ],
  "jobs": [
    { "id": "job0", "time_on_site": "02:00", "location": "39.065400, -108.547134" },
    { "id": "job1", "time_on_site": "02:00", "location": "39.070210, -108.564048" },
    { "id": "job2", "time_on_site": "02:00", "location": "39.070329, -108.570304" },
    { "id": "job3", "time_on_site": "02:00", "location": "39.075499, -108.560484" },
    { "id": "job4", "time_on_site": "02:00", "location": "39.072802, -108.549038" }
  ],
  "drivers": [
    { "id": "driver0", "max_multiday_days": 5 }
  ]
}

The routing_with_multiday_build.json request. Click here to open it in the UI

Run the request in the command line using cURL:

curl -u "youraccount%3Amain:password" -H "Content-Type: application/json" --data-binary "@routing_with_multiday_build.json" -L "https://routecloud.telogis.com/v1/build?wait=1"

Substitute youraccount%3Amain for your username (replacing the colon with %3A), and password with your password. See the Authentication topic for more information and alternative authentication methods. The wait=1 parameter instructs RouteCloud to return the results synchronously. This means that results are returned directly to the command window. See Retrieving API Results for more information about synchronous and asynchronous tasks.

The build request defines three routes, one driver and five jobs:

driver0 has driver.max_multiday_days set to 5, allowing them to have a multi-day route up to five days in length.
The route start/end locations are in Denver, while the job locations are in Grand Junction, a city four hours away, making a multi-day route with overnight stays more efficient.

Build Response

{
  "routes": [
    {
      "id": "route0", ...
      "next_multiday_day": "route1",
      "stops": [
        { "type": "depot", ... },
        { "type": "job", "id": "job0", ... },
        { "type": "overnight", "location": "39.065400,-108.547134", ... }
      ]
    },
    {
      "id": "route1", ...
      "previous_multiday_day": "route0",
      "next_multiday_day": "route2",
      "stops": [
        { "type": "overnight", "location": "39.065400,-108.547134", ... },
        { "type": "job", "id": "job2", ... },
        { "type": "job", "id": "job1", ... },
        { "type": "job", "id": "job3", ... },
        { "type": "overnight", "location": "39.075499,-108.560484", ... }
      ]
    },
    {
      "id": "route2", ...
      "previous_multiday_day": "route1",
      "stops": [
        { "type": "overnight", "location": "39.075499,-108.560484", ... },
        { "type": "job", "id": "job4", ... },
        { "type": "depot", ... }
      ]
    }
  ],
  "unrouted_jobs": []
}

The routing_with_multiday_build_response.json response. Click here to open it in the UI.

RouteCloud produced a three-day multi-day route. route0 ends with an overnight stay at 39.065400,-108.547134, which is the location of its final job, job0. The following day, route1 starts from 39.065400,-108.547134 as that was the previous day's overnight location. Note that route0 has next_multiday_day set to route1 as that is the route that follows next in the multi-day route.

{
  "routes": [
    {
      "id": "route0",
      "location": "39.730489,-104.989109",
      "date": "2016-03-14",
      "driver": "driver0",
      "start_time": "09:00",
      "max_working_time": "08:00",
      "jobs": ["job0"],
      "has_next_multiday_day": true
    },
    {
      "id": "route1",
      "location": "39.730489,-104.989109",
      "date": "2016-03-15",
      "driver": "driver0",
      "start_time": "09:00",
      "max_working_time": "08:00",
      "jobs": ["job2", "job3"],
      "has_next_multiday_day": true
    },
    {
      "id": "route2",
      "location": "39.730489,-104.989109",
      "date": "2016-03-16",
      "driver": "driver0",
      "start_time": "09:00",
      "max_working_time": "08:00",
      "jobs": ["job4"],
      "has_next_multiday_day": false
    }
  ],
  "jobs": [
    { "id": "job0", "time_on_site": "02:00", "location": "39.065400, -108.547134" },
    { "id": "job1", "time_on_site": "02:00", "location": "39.070210, -108.564048" },
    { "id": "job2", "time_on_site": "02:00", "location": "39.070329, -108.570304" },
    { "id": "job3", "time_on_site": "02:00", "location": "39.075499, -108.560484" },
    { "id": "job4", "time_on_site": "02:00", "location": "39.072802, -108.549038" }
  ],
  "drivers": [
    { "id": "driver0", "max_multiday_days": 5 }
  ],
  "job": "job1" // Recommend an insertion position for job1
}

The routing_with_multiday_recommend.json request.

The recommend request defines three routes, all linked into one multi-day route. There are four jobs already on the routes. job1 is the job to insert:

driver0 has driver.max_multiday_days set to 5, allowing them to have a multi-day route up to five days in length.
route0, route1 and route2 all form a three-day multi-day route.
route0 and route1 both end with an overnight stay, indicated by route.has_next_multiday_day being set to true.
route2 is the last day of the multi-day route, and so has route.has_next_multiday_day set to false.

{
  "recommend_options": [
    {
      "route_index": 1,
      "job_index": 1,
      "routes": [
        {
          "id": "route0", ...
          "next_multiday_day": "route1",
          "stops": [
            { "type": "depot", ... },
            { "type": "job", "id": "job0", ... },
            { "type": "overnight", ... }
          ]
        },
        {
          "id": "route1", ...
          "previous_multiday_day": "route0",
          "next_multiday_day": "route2",
          "stops": [
            { "type": "overnight", ... },
            { "type": "job", "id": "job2", ... },
            { "type": "job", "id": "job1", ... },
            { "type": "job", "id": "job3", ... },
            { "type": "overnight", ... }
          ]
        },
        {
          "id": "route2", ...
          "previous_multiday_day": "route1",
          "stops": [
            { "type": "overnight", ... },
            { "type": "job", "id": "job4", ... },
            { "type": "depot", ... }
          ]
        }
      ],
    ...
    },
    { ... },
    { ... }
  ]
}

A snipped version of the routing_with_multiday_recommend.json response. The full response is available here.

RouteCloud returned three recommend_options. The best recommend_option is returned as the first element in recommend_options:

All days of the modified multi-day route are returned on recommend_option.routes.
route_index is 1, as job1 has been inserted onto route1, which is at index 1 in the recommend_option.routes array.
job_index is 1, as job1 has been inserted at index 1 in the stops array when only counting stops of type "job".

Violations

Multi-day routes that span more days than driver.max_multiday_days receive a multiday_route_over_max_days violation on their route response object.

Note

build requests should never produce a multiday_route_over_max_days violation, but sequence, recommend, and evaluate requests may.

Routing with Multi-day Routes

Note

Overview

Using Multi-day Routes

Load Capacity and Multi-day Routes

Build Example

Build Request

Build Response

Recommend Example

Recommend Request

Recommend Response

Violations

Note

See Also