Recommend Route

Route recommendation examines all potential insertions for a single job and returns the top max_results. It differs from an insert call in that it provides multiple options for a single job, instead of one option for multiple jobs.

Query Parameters

  • wait=1 - Optional. Wait until the recommend completes before returning the result. See Retrieving API Results.

Status Codes

recommend_request

The recommend_request type inherits all fields from problem.

Name Type Description
allow_hard_constraint_violations boolean Defines if returning results that cause hard constraint violations are allowed. Defaults to false.
custom custom Inherited. User-supplied custom fields that are returned unmodified in the response. These have no effect on optimization.
drivers driver[] Inherited. If specified, the drivers involved in this route recommendation.
id string Inherited. An identifier for the request. See Request IDs.
job job The job to be inserted.
jobs job[] Inherited. The jobs involved in the recommend.
markers marker[] Inherited. The markers involved in this request. If defined here, markers can be referenced by id elsewhere; for example, job.location.
max_results integer The maximum number of results to return from the recommend request. Defaults to 10. Set to -1 to return all possible results.
max_results_per_date integer The maximum number of results to return for each date. Defaults to no limit. Leave empty or set to -1 for no per-date limit.
max_results_per_driver integer The maximum number of results to return for each driver. Defaults to no limit. Leave empty or set to -1 for no per-driver limit.
max_results_per_route integer The maximum number of results to return for each route. Defaults to no limit. Leave empty or set to -1 for no per-route limit.
name string Inherited. A name for the request. See Request IDs.
routes route[] Inherited. Routes to consider inserting the new job into.
schedules schedule[] Inherited. If specified, applies recurring schedule constraints to the jobs.
settings settings Inherited. Settings to apply during the recommend call.
vehicles vehicle[] The vehicles involved in this optimization problem. If defined here, vehicles can be referenced by id elsewhere; for example, route.vehicle. 
{
  "id": "request+1234567",
  "name": "territory1",
  "job" : {
    "id" : "job_to_recommend",
    "location": "-43.549062, 172.642059",
    "required_route_attributes" : [ "second_delivery" ],
    "time_window" : { "start" : "10:00", "end" : "11:00" }
  },
  "max_results": 1,
  "allow_hard_constraint_violations": false,
  "routes": [
    {
      "id": "route0", 
      "start_time": "08:30", 
      "max_working_time": "09:00",
      "location": "-43.552723, 172.634758",
      "jobs": [
        { "id": "job0", "time_on_site": "00:10", "location": "-43.549062, 172.642059" },
        { "id": "job1", "time_on_site": "00:10", "location": "-43.544839, 172.628252" }
      ]
    },
    {
      "id": "route1", 
      "start_time": "08:30", 
      "max_working_time": "09:00",
      "location": "-43.552723, 172.634758",
      "route_attributes": [ "second_delivery" ],
      "jobs": [
        { "id": "job2", "time_on_site": "00:10", "location": "-43.549062, 172.642059" },
        { "id": "job3", "time_on_site": "00:10", "location": "-43.544839, 172.628252" }
      ]
    }
  ]
}

An example recommend request.

recommend_response

Name Type Description
custom custom User-supplied custom fields that were sent in the request.
recommend_options recommend_option[] Insert options for the job. 
{
  "recommend_options": [
    {
      "delta_cost": 15.55,
      "delta_internal_cost": 18.21,
      "delta_working_time": "01:02:12",
      "delta_distance_meters": 1278.0,
      "job_index": 2,
      "route": {
        "id": "route1",
        "cost": 23.29,
        "internal_cost": 134.11,
        "distance_meters": 5432.0,
        "working_time": "01:33:10",
        "driving_time": "00:13:32",
        "stops": [
          {
            "location": "-43.552723,172.634758",
            "type": "depot",
            "arrival_time": "08:30:00",
            "time_on_site": "00:00:00",
            "distance_to_meters": 0.0,
            "time_to": "00:00:00"
          },
          {
            "type": "job",
            "id": "job2",
            "arrival_time": "08:33:16",
            "time_on_site": "00:10:00",
            "distance_to_meters": 992.0,
            "time_to": "00:03:16"
          },
          {
            "type": "job",
            "id": "job3",
            "arrival_time": "08:46:54",
            "time_on_site": "00:10:00",
            "distance_to_meters": 1726.0,
            "time_to": "00:03:38"
          },
          {
            "type": "job",
            "id": "job_to_recommend",
            "arrival_time": "10:00:00",
            "time_on_site": "00:00:00",
            "idle_time": "00:59:38",
            "distance_to_meters": 1722.0,
            "time_to": "01:03:06"
          },
          {
            "location": "-43.552723,172.634758",
            "type": "depot",
            "arrival_time": "10:03:10",
            "time_on_site": "00:00:00",
            "distance_to_meters": 992.0,
            "time_to": "-00:56:28"
          }
        ]
      }
    }
  ]
}

An example recommend response.

See Also