Sequencing Routes

Sequencing operations reorder the jobs on a route to minimize cost, but also to respect any constraints present. The sequencing service can be accessed via the /v1/sequence endpoint. Sequencing will not unroute jobs, nor will it move jobs between routes. Sequencing operations are completed rapidly, and even large requests take only seconds.

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.

Request

{
  "routes": [
    {
      "id": "route0",
      "location": "39.718005, -104.969531",
      "start_time": "09:00",
      "breaks": [
        { "id": "route0_morning_break", "start": "11:00", "length": "00:15" },
        { "id": "route0_lunch_break", "start": "13:00", "length": "00:30" },
        { "id": "route0_afternoon_break", "start": "15:00", "length": "00:15" }
      ],
      "jobs": [
        "job4", "job11", "job9", "job6", "job8"
      ]
    }, {
      "id": "route1",
      "location": "39.718005, -104.969531",
      "start_time": "09:00",
      "jobs": [
        { "id": "job3", "time_on_site": "00:10", "location": "39.653975, -105.093750" },
        { "id": "job1", "time_on_site": "00:10", "location": "39.725375, -104.791080" },
        { "id": "job7", "time_on_site": "00:10", "location": "39.727919, -105.103126" },
        { "id": "job5", "time_on_site": "00:10", "location": "39.638635, -105.128906", "required_route_attributes": [ "hazmat" ] },
        { "id": "job10", "time_on_site": "00:10", "location": "39.749546, -105.069141" },
        { "id": "job0", "time_on_site": "00:10", "location": "39.635928, -105.049219" },
        { "id": "job2", "time_on_site": "00:15", "location": "39.708990, -105.026954" }
      ]
    }
  ],
  "jobs": [
    { "id": "job4", "time_on_site": "00:15", "location": "39.590789, -105.084376" },
    { "id": "job6", "time_on_site": "00:10", "location": "39.597111, -105.041015" },
    { "id": "job8", "time_on_site": "00:10", "location": "39.615167, -104.887500", "time_window": { "start" : "13:00", "end" : "15:00" }  },
    { "id": "job9", "time_on_site": "00:10", "location": "39.820688, -105.133594" },
    { "id": "job11", "time_on_site": "00:10", "location": "39.556465, -104.976563" }
  ]
}

route_sequencing_request.json sequencing request - download it here. Click here to open in the UI.

Unsequenced Routes
Image of the routes defined by route_sequencing_request.json before sequencing.

route_sequencing_request.json defines two routes. As shown in the image above, these routes are currently inefficiently sequenced.
route0 (the purple route) has five jobs, defined using references, and three driver breaks. job8 has a time window of 1:00 PM to 3:00 PM, so will be sequenced later in the route.
route1 (the green route) has seven jobs, defined inline. job5 requires the hazmat attribute, which route1 does not provide. Sequencing cannot unroute jobs, so the job will remain routed but will produce a missing_route_attributes violation.
job9 would be better serviced by route1 (the green route). Sequencing cannot move stops between routes, so the job will remain on route0 (the purple route).

You can run the request in the command line using cURL:

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

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.

Response

{
  "routes": [
    {
      "id": "route0", ...
      "stops": [
        { "type": "depot", ... },
        { "id": "job9", ... },
        { "id": "job4", ... },
        { "id": "job6", ... },
        { "id": "route0_morning_break", ... },
        { "id": "job11", ... },
        { "id": "route0_lunch_break", ... },
        { "id": "job8", ... },
        { "type": "depot", ... }
      ]
    },
    {
      "id": "route1", ...
      "stops": [
        { "type": "depot", ... },
        { "id": "job1", ... },
        { "id": "job10", ... },
        { "id": "job7", ... },
        { "id": "job5", "violations": [ { "type": "missing_route_attributes" } ], ... },
        { "id": "job3", ..},
        { "id": "job0", ... },
        { "id": "job2", ... },
        { "type": "depot", ... }
      ]
    }
  ]
}

A snipped version of the route_sequencing_request.json response. The full response is available here. Click here to open in the UI.

Sequenced Routes
Image of the routes defined by route_sequencing_request.json after sequencing.

Field Before Sequencing After Sequencing Difference
Total Distance 207 Miles 137 Miles -80 Miles
Total Time 09:02 08:17 -00:45

As illustrated in the table above, sequencing decreases both the total distance and time of the routes. When you compare the images of the routes you can see the difference sequencing makes - the routes no longer reverse direction, looping back on themselves on the same streets. Note that job8 was placed in the afternoon on route0 to minimize idle time before the 1:00 PM time window opened. job5 still has a missing_route_attributes violation, as sequencing alone cannot remove the violation.

What Next?