Recommending Routes

Route recommendation operations calculate the best potential insertion positions of a job in a route, ordered by quality. Recommending takes into account all constraints by returning recommendations that violate fewer constraints higher in the ordered results list. The recommendation service can be accessed via the /v1/recommend endpoint. Route recommendation 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",
      "jobs": [
        { "id": "job0", "time_on_site": "00:15", "location": "39.590789, -105.084376" },
        { "id": "job1", "time_on_site": "00:10", "location": "39.597111, -105.041015" }
      ]
    }, {
      "id": "route1",
      "location": "39.718005, -104.969531",
      "start_time": "09:00",
      "jobs": [
        { "id": "job2", "time_on_site": "00:10", "location": "39.749546, -105.069141" },
        { "id": "job3", "time_on_site": "00:10", "location": "39.727919, -105.103126" }
      ]
    }
  ],
  "job": { "id": "job", "time_on_site": "00:10", "location": "39.820688, -105.133594" },
  "max_results": 2,
  "allow_hard_constraint_violations": false
}

route_recommendation_request.json recommend request - download it here. Click here to open in the UI.

route_recommendation_request.json defines two simple routes and a single job for which the optimizer will recommend optimal insertion positions.
max_results is set to 2, so no more than two results will be returned. By default, max_results is set to 10. When set to -1 all possible results are returned.
allow_hard_constraint_violations is set to false. If it is set to true the recommend request may also return results that cause violations. Insertion options that cause violations are usually more expensive than those that do not, so will be near the end of the recommend_options results array.

In the image below, the unrouted job (in the top left corner of the image) is close to the stops on route1 (the purple route). The best insertion options would be on route1.

Recommend Routes Request
Image of the routes and job to insert, defined by route_recommendation_request.json.

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

curl -u "youraccount%3Amain:password" "https://routecloud.telogis.com/v1/recommend?wait=1" -H "Content-Type: application/json" --data-binary "@route_recommendation_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

{
  "recommend_options": [
    {
      "delta_cost": 16.46,
      "delta_internal_cost": 21.59,
      "delta_working_time": "00:42:42",
      "delta_distance_meters": 28944.0,
      "route_index": 0,
      "job_index": 1,
      "routes": [
        {
          "id": "route1", ...
          "stops": [
            { "type": "depot", ... },
            { "id": "job2", ... },
            { "id": "job", ...  },
            { "id": "job3", ... },
            { "type": "depot", ... }
          ]
        }
      ]
    }, {
      "delta_cost": 17.05,
      "delta_internal_cost": 22.15,
      "delta_working_time": "00:42:22",
      "delta_distance_meters": 32280.0,
      "route_index": 0,
      "job_index": 0,
      "routes": [
        {
          "id": "route1", ...
          "stops": [
            { "type": "depot", ... },
            { "id": "job", ... },
            { "id": "job2", ... },
            { "id": "job3", ... },
            { "type": "depot", ... }
          ]
        }
      ]
    }
  ]
}

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

The response consists of two recommend_options. As expected, both insertion recommendations are for route1, because route1 is closer to the job than route0. The options are ordered by increasing delta_internal_cost; delta_cost, delta_working_time, and delta_distance_meters are also returned for convenience.

The first option, where job is the second job on route1, is more cost-effective than the second option, where job is the first job. Having job as the second job decreases the distance of the route. Only two options were returned because max_results was set to 2 in the request. If it were set higher, then options for route0 would also be returned.

The job_index indicates the position of the inserted job by counting the number of stops of type job preceding the insertion position. Depot stops and breaks aren't counted in the indexing. The job_index counts jobs only on the day containing the inserted job. It does not count jobs on preceding days of a multi-day route.

The routes field shows what the single-day or multi-day route will look like if the job is inserted at the provided job_index. If inserting onto a single-day route, routes will contain just one route. If inserting onto a multi-day route, routes will contain all days of the multi-day route.

The route_index field indicates which day of the multi-day route contains the inserted job. The route_index field is always 0 for single-day routes.

What Next?