• Home
  • Guides
  • Reference
  • Support

    Show / Hide Table of Contents
    • API Overview
      • Overview
      • Authentication
      • Retrieving API Results
      • Referenced vs Inline Entities
      • Choosing API Response Data
      • Handling API Errors
    • separator
    • Vehicle Routing Endpoints
      • Path
    • Optimization Endpoints
      • Instantiate
      • Build
      • Assignment Restrictions
      • Optimize
      • Sequence
      • Evaluate
      • Recommend
      • Insert
      • Centroids
      • Zones
      • Consolidate By Job Restrictions
      • Consolidate By Route Assignments
    • Geocoding Endpoints
      • Geocode
      • Reverse Geocode
    • Task Endpoints
      • List
      • Status
      • Result
      • Cancel
    • Sandbox Endpoints
      • List
      • Create
      • Rename
      • Retrieve
      • Update
      • Delete
      • Revisions
      • Add Revision
      • Expiry
      • Permissions
    • Verizon Connect Fleet Integration Endpoints
      • Pull Platform Data
      • Sync Platform Data
      • List Platform Territories
    • Other Endpoints
      • Canonicalize
      • Route Cards
      • Validate
      • Version
    • separator
    • Request Types
      • problem
      • capacity_metric
      • depot
      • driver
      • driver_break
      • job
      • job_template
      • job_type
      • load_amount
      • marker
      • problem_defaults
      • route
      • schedule
      • settings
      • shift
      • shift_override
      • shift_pattern
      • shift_pattern_assignment
      • stop
      • vehicle
      • zone
      • variance
    • Response Types
      • instantiate_response
      • problem_response
      • problem_aggregates
      • driver_response
      • geocoded_location
      • recommend_option
      • route_response
      • schedule_response
      • schedule_instantiate_response
      • stop_response
      • violation
    • Meta Types
      • task_redirect_response
      • task_status_response
      • validate_response
    • Sandbox Types
      • delta
      • array_delta
      • dict_delta
      • keyed_array_delta
      • object_delta
      • set_delta
      • revision
      • revision_created_response
      • revision_response
      • sandbox_response
    • Common Types
      • date_range
      • day_of_week
      • hazmat_load_type
      • id
      • latlon
      • stop_type
      • time_window
      • custom
      • polygon
    • Primitive Types
      • boolean
      • date
      • datetime
      • float
      • integer
      • string
      • timespan

    Recommend Route

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

    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

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

    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

    • Recommending Routes