Evaluate Routes

• POST https://routecloud.telogis.com/v1/evaluate.
• Authentication required.
• Request body: evaluate_request.
• Response body: If wait=1 specified, returns the task result (see below). Otherwise, returns a task_redirect_response.
• Task result:
  • If aggregate=1 specified, returns a problem_aggregates.
  • Otherwise, if return_request is true, returns a problem.
  • Otherwise, returns an evaluate_response.

The evaluate routes call takes a set of routes with jobs assigned to them, and calculates their costs, distances, arrival times, breaks, and violations. The evaluate call does not perform any optimization tasks - the job sequence is not changed. It simply inserts the required start/end depots and driver breaks, then evaluates the route as-is. If your users are manually inserting jobs or manipulating routes, you can use this to update the arrival times of jobs or check for violations.

Query Parameters

• wait=1 - Optional. Wait until the evaluate completes before returning the result. See Retrieving API Results.
• aggregate=1 - Optional. Return a problem_aggregates object summarizing the evaluation result, instead of the full response. Only applies if wait=1 is specified; otherwise should be specified when retrieving the task result.

Status Codes

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

evaluate_request

The evaluate_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 evaluate call.
id	string	Inherited. An identifier for the request. See Request IDs.
jobs	job[]	Inherited. The jobs involved in this evaluate call.
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.
return_request	boolean	Optional. Defines if the original request, with calculated values, is returned as the response. If not, an Evaluate Response is returned. See Full vs Partial Responses. Defaults to false.
routes	route[]	Inherited. The routes to evaluate.
schedules	schedule[]	Inherited. If specified, applies recurring schedule constraints to the jobs.
settings	settings	Inherited. The settings to apply during the evaluation.
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",
      "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" }
      ]
    }
  ]
}

An example evaluate request.

evaluate_response

Note

The result of a evaluate is a problem instead of a evaluate_response, if return_request was set to true on the input.

The evaluate_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 depots, breaks, arrival times, distances, and violations.
schedules	schedule_response[]	Inherited. Schedules that had their base dates assigned, if any. See Routing with Schedules.

{
  "routes": [
    {
      "id": "route0",
      "cost": 7.74,
      "internal_cost": 115.91,
      "distance_meters": 4154.0,
      "working_time": "00:30:58",
      "driving_time": "00:10:58",
      "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"
        },
        {
          "location": "-43.552723,172.634758",
          "type": "depot",
          "arrival_time": "09:00:58",
          "time_on_site": "00:00:00",
          "distance_to_meters": 1436.0,
          "time_to": "00:04:04"
        }
      ]
    }
  ]
}

An example evaluate response.

See Also

• Evaluating Routes.