Inserting Jobs

The insert jobs operation inserts a list of jobs into routes without changing the sequencing of the existing jobs. Job insertion takes into account all constraints, and attempts to insert jobs into locally optimal locations. If a job is not routable, it is placed in the unrouted_jobs list. Insert operations are completed rapidly, and even large requests take only seconds.

Job insertion requests cannot change the ordering of existing stops, so the returned routes are not globally optimal. In addition, job insertion quality decreases if there are few existing jobs on the routes. If you require optimal routes you should perform a full rebuild instead or, for individually-optimal routes, perform a sequence operation after insertion.

Note

To run the examples in this tutorial, you will need:

  • A RouteCloud API login. Use your Verizon Connect Enterprise username and password to authenticate with the RouteCloud API. To obtain a username and password, contact Verizon Connect sales.
  • cURL to run the requests. You can download a cURL binary from here.

Request

{
  "routes": [
    {
      "id": "route0",
      "location": "39.718005, -104.969531",
      "start_time": "09:00",
      "jobs": [
        { "id": "job0", "time_on_site": "00:15", "location": "39.590789, -105.084376" },
        { "id": "job1", "time_on_site": "00:10", "location": "39.597111, -105.041015" }
      ]
    }, {
      "id": "route1",
      "location": "39.718005, -104.969531",
      "start_time": "09:00",
      "jobs": [
        { "id": "job2", "time_on_site": "00:10", "location": "39.749546, -105.069141" },
        { "id": "job3", "time_on_site": "00:10", "location": "39.727919, -105.103126" }
      ]
    }
  ],
  "jobs_to_insert": [
    { "id": "job_to_insert1", "time_on_site": "00:10", "location": "39.820688, -105.133594" },
    { "id": "job_to_insert2", "time_on_site": "00:15", "location": "39.825626, -105.130460" },
    { "id": "job_to_insert3", "location": "39.825626, -105.130460", "required_route_attributes": ["unsatisfiable"] }
  ],
  "allow_hard_constraint_violations": false
}

insert_jobs_request.json insert request - download it here. Click here to open in the UI.

insert_jobs_request.json defines two simple routes and three jobs to insert. job_to_insert and job_to_insert2 will be inserted into locally optimal positions on the routes. job_to_insert3 will not be inserted, because it cannot be routed without hard constraint violations and allow_hard_constraint_violations is set to false. If allow_hard_constraint_violations were set to true, the job would be inserted regardless of the violation.

You can run the request in the command line using cURL:

curl -u "youraccount%3Amain:password" "https://routecloud.telogis.com/v1/insert?wait=1" -H "Content-Type: application/json" --data-binary "insert_jobs_request.json" -L

Substitute youraccount%3Amain for your username (replacing the colon with %3A), and password with your password. See the Authentication topic for more information and alternative authentication methods. The wait=1 parameter instructs RouteCloud to return the results synchronously. This means that results are returned directly to the command window. See Retrieving API Results for more information about synchronous and asynchronous tasks.

Response

{
  "routes": [
    {
      "id": "route0", ...
      "stops": [
        { "type": "depot", ... },
        { "id": "job0", ... },
        { "id": "job1", ... },
        { "type": "depot", ... }
      ]
    },
    {
      "id": "route1",
      "stops": [
        { "type": "depot", ... },
        { "id": "job2", ... },
        { "id": "job_to_insert1", ... },
        { "id": "job_to_insert2", ... },
        { "id": "job3", ... },
        { "type": "depot", ... }
      ]
    }
  ],
  "unrouted_jobs": [
    { "id": "job_to_insert3" }
  ]
}

A snipped version of the insert_jobs_response.json response, the full response is available here. Click here to open in the UI.

The response object consists of an array of route objects, and an array of unrouted jobs. job_to_insert and job_to_insert2 were placed in optimal positions on route1. job_to_insert3 was not routed because it would cause a missing_route_attributes violation and allow_hard_constraint_violations was set to false.

What Next?