Calculate Centroids

POST https://routecloud.telogis.com/v1/centroids.
Authentication required.
Request body: centroids_request.
Response body: If wait=1 specified, returns the task result (see below). Otherwise, returns a task_redirect_response.
Task result: centroids_response.

Image of centroids

The centroids call calculates a geographic centroid for each driver, considering all constraints. These centroids may be input into future build calls (via driver.centroid) to keep the driver returning to the same geographic location. The centroids call places driver centroids close to the jobs assignable to that driver. It considers constraints such as job.required_driver/route.driver, job.required_route_attributes/route.route_attributes, and job.date/route.date. The centroids call distributes driver centroids throughout the jobs, with centroids being attracted to regions of greater job density. If any driver.centroids are input, they are used to seed the algorithm.

Query Parameters

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

Status Codes

200 - Success.
302 - If wait=1 was provided and the centroids 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.

centroids_request

The centroids_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. The drivers to place centroids for.
id	string	Inherited. An identifier for the request. See Request IDs.
jobs	job[]	Inherited. The jobs that can be assigned to routes.
markers	marker[]	Inherited. The markers involved in this request. 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.
routes	route[]	Inherited. The routes to put jobs on.
schedules	schedule[]	Inherited. If specified, specifies recurring schedule constraints on the jobs.
settings	settings	Inherited. The settings to apply.

{
  "id": "request+1234567",
  "name": "territory1",
  "drivers": [
    { "id": "driver0" },
    { "id": "driver1" }
  ],
  "routes": [
    { "id": "route0", "driver": "driver0", "start_time": "08:30", "max_working_time": "09:00", "location": "-43.552723, 172.634758" },
    { "id": "route1", "driver": "driver1", "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" }
  ]
}

An example centroids request.

centroids_response

The centroids_response type inherits all fields from problem_response.

Name	Type	Description
custom	custom	User-supplied custom fields that were sent in the request.
drivers	driver_response[]	Drivers populated with centroids.

{
  "drivers": [
    {
      "id": "driver0",
      "centroid": "-43.537166,172.622004"
    },
    {
      "id": "driver1",
      "centroid": "-43.534501,172.621811"
    }
  ]
}

An example centroids response.

Example

This feature is best demonstrated on a large number of points. This file contains 25 drivers with 1000 points of interest in the Los Angeles area (click here to open it in the UI). To place centroids in the UI, go to the Drivers tab, select all drivers (Ctrl+A), then click Auto-Place.

Notes

The driver.centroid feature is sometimes called "advanced territories" or "gravity points".