Evaluating Routes

The evaluate routes call takes a set of routes, and calculates their costs, distances, arrival times, breaks, and violations. The evaluation operation does not perform any route optimization tasks - the job sequence is not changed. The evalute call can be used to calculate the time and distance of a route before making a sequence request, thus computing the time and distance savings of the new sequencing. It can also be used to update arrival times when a job is manually inserted onto a route.

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_evaluation_request.json evaluation request - download it here. Click here to open it in the UI.

route_evaluation_request.json defines two routes.
route0 has five jobs, defined using references, and three driver breaks. job8 has a time window of 1:00 PM to 3:00 PM, so the route will idle until 1:00 PM before delivering this job.
route1 has seven jobs, defined inline. job5 requires the hazmat attribute; route1 does not provide this attribute, so the job will produce a missing_route_attributes violation.

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

curl -u "youraccount%3Amain:password" "https://routecloud.telogis.com/v1/evaluate?wait=1" -H "Content-Type: application/json" --data-binary "@route_evaluation_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",
      "cost": 109.82,
      "internal_cost": 242.89,
      "distance_meters": 177332.0,
      "working_time": "04:57:24",
      "driving_time": "02:44:32",
      "stops": [
        {
          "location": "39.718005,-104.969531",
          "type": "depot",
          "arrival_time": "09:00:00",
          "time_on_site": "00:00:00",
          "distance_to_meters": 0.0,
          "time_to": "00:00:00"
        },
        {
          "type": "job",
          "id": "job4",
          "arrival_time": "09:29:54",
          "time_on_site": "00:15:00",
          "distance_to_meters": 23942.0,
          "time_to": "00:29:54"
        },
        { "id": "job11", ... },
        { "id": "job9", ... },
        {
          "type": "break",
          "id": "route0_morning_break",
          "arrival_time": "11:00:00",
          "time_on_site": "00:15:00",
          "distance_to_meters": 0.0,
          "time_to": "00:00:00"
        },
        { "id": "job6", ... },
        { "id": "route0_lunch_break", ... },
        {
          "type": "job",
          "id": "job8",
          "arrival_time": "13:30:00",
          "time_on_site": "00:10:00",
          "idle_time": "00:32:52",
          "distance_to_meters": 28634.0,
          "time_to": "00:22:28"
        },
        { "type": "depot", ... }
      ]
    },
    {
      "id": "route1", ... 
      "stops": [
        { "type": "depot", ... },
        { "id": "job3", ... },
        { "id": "job1", ... },
        { "id": "job7", ... },
        {
          "type": "job",
          "id": "job5",
          "arrival_time": "11:12:04",
          "time_on_site": "00:10:00",
          "distance_to_meters": 12706.0,
          "time_to": "00:14:26",
          "violations": [ { "type": "missing_route_attributes" } ]
        },
        { "id": "job10", ... },
        { "id": "job0", ... },
        { "id": "job2", ... },
        { "type": "depot", ... }
      ]
    }
  ]
}

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

The response contains route0 and route1, with breaks, violations, times, distances in meters, and costs calculated.
Morning and lunch breaks were inserted on route0, 32 minutes of idle time was inserted before job8, and a missing_route_attributes violation was added to job5 on route1.

What Next?