• 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

    Build Routes

    • POST https://routecloud.telogis.com/v1/build.
    • Authentication required.
    • Request body: build_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 build_response.

    The build routes call generates new routes using a collection of empty routes and jobs. The build request attempts to place as many jobs as possible onto the given routes while minimizing cost and avoiding constraint violations. If it is not possible to place a job on a route, it is placed in the unrouted_jobs list. Note that the resulting stops list contains references to depots, jobs, and breaks.

    Query Parameters

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

    Status Codes

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

    build_request

    The build_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 build.
    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 build. 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, a Build 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 build.
    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 build request.

    build_response

    Note

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

    The build_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 build response.

    See Also

    • Building Routes.
    • Routing with Shifts.
    • Routing with Time Windows.
    • Routing with Dates.
    • Routing with Attributes.
    • Routing with Driver Breaks.
    • Routing with Capacities.
    • Routing with Schedules.