Optimize Routes

POST https://routecloud.telogis.com/v1/optimize.
Authentication required.
Request body: optimize_request.
Response body: If wait=1 specified, returns the task result (see below). Otherwise, returns a task_redirect_response.
Task result: If return_request is true, returns a problem. Otherwise, returns a optimize_response.

The optimize routes call attempts to arrange jobs onto routes in an optimal fashion, minimizing cost and avoiding contraint violations. The optimize request is significantly faster than the build request as it has a reduced set of optimizations it can apply.

Query Parameters

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

Status Codes

200 - Success.
302 - If wait=1 was provided and the optimize result is not yet available, a redirect is sent instead of a normal result every 15 seconds to refresh the HTTP timeout. See Retrieving API Results.
400 - The input problem is invalid. The response is an error_response.
401 - Authentication required.
429 - Exceeded usage limits.

optimize_request

The optimize_request type inherits all fields from problem.

Name	Type	Description
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 optimization.
id	string	Inherited. An identifier for the request. See Request IDs.
jobs	job[]	Inherited. The jobs to assign to routes.
markers	marker[]	Inherited. The markers involved in this optimization. If defined here, markers can be referenced by id elsewhere; for example, job.location.
name	string	Inherited. A name for the request. See Request IDs.
return_request	boolean	Optional. Defines if the original request, with calculated values, is returned as the response. If not, an Optimize Response is returned. See Full vs Partial Responses. Defaults to `false`.
routes	route[]	Inherited. The routes to put jobs on.
schedules	schedule[]	Inherited. If specified, applies recurring schedule constraints to the jobs.
settings	settings	Inherited. The settings to apply during the optimization.
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",
  "routes": [
    { "id": "route0", "start_time": "08:30", "max_working_time": "09:00", "location": "-43.552723, 172.634758" },
    { "id": "route1", "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": "job2", "time_on_site": "00:15", "location": "-43.551746, 172.610160" },
    { "id": "job3", "time_on_site": "00:18", "location": "-43.522026, 172.630837" },
    { "id": "job4", "time_on_site": "00:15", "location": "-43.511665, 172.598252" }
  ],
  "settings": {
    "time_windows_as_hard_constraint": true
  }
}

An example optimize request.

optimize_response

Note

The result of a optimization is a problem instead of an optimize_response, if return_request was set to true on the input.

The optimize_response type inherits all fields from problem_response.

Name	Type	Description
custom	custom	Inherited. User-supplied custom fields that were sent in the request.
routes	route_response[]	Inherited. Routes populated with stops.
schedules	schedule_response[]	Inherited. Schedules that had their base dates assigned, if any. See Routing with Schedules.
unrouted_jobs	stop_response[]	Inherited. Jobs that could not be routed.

{
  "routes": [
    {
      "id": "route0",
      "cost": 31.88,
      "internal_cost": 149.85,
      "distance_meters": 17652.0,
      "working_time": "01:53:24",
      "driving_time": "00:45:24",
      "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": "job0",
          "arrival_time": "08:33:16",
          "time_on_site": "00:10:00",
          "distance_to_meters": 992.0,
          "time_to": "00:03:16"
        },
        {
          "type": "job",
          "id": "job1",
          "arrival_time": "08:46:54",
          "time_on_site": "00:10:00",
          "distance_to_meters": 1726.0,
          "time_to": "00:03:38"
        },
        {
          "type": "job",
          "id": "job3",
          "arrival_time": "09:05:08",
          "time_on_site": "00:18:00",
          "distance_to_meters": 2872.0,
          "time_to": "00:08:14"
        },
        {
          "type": "job",
          "id": "job4",
          "arrival_time": "09:32:04",
          "time_on_site": "00:15:00",
          "distance_to_meters": 3710.0,
          "time_to": "00:08:56"
        },
        {
          "type": "job",
          "id": "job2",
          "arrival_time": "10:01:22",
          "time_on_site": "00:15:00",
          "distance_to_meters": 5432.0,
          "time_to": "00:14:18"
        },
        {
          "location": "-43.552723,172.634758",
          "type": "depot",
          "arrival_time": "10:23:24",
          "time_on_site": "00:00:00",
          "distance_to_meters": 2920.0,
          "time_to": "00:07:02"
        }
      ]
    },
    {
      "id": "route1",
      "cost": 0.0,
      "internal_cost": 0.0,
      "distance_meters": 0.0,
      "working_time": "00:00:00",
      "driving_time": "00:00:00",
      "stops": []
    }
  ],
  "unrouted_jobs": []
}

An example optimize response.