Routing with Time Windows

It is possible to specify two time windows for a job. RouteCloud attempts to arrive at the job within one of these time windows. If settings.time_windows_as_hard_constraint is set to true, jobs are not routed if their time window constraint cannot be met. If a driver is early for a time window, then RouteCloud always idles until the time window opens.

By default, settings.time_windows_as_hard_constraint is set to true.

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:10", "location": "39.635928, -105.049219" },
    { "id": "job1", "time_on_site": "00:10", "location": "39.638635, -105.128906", "time_window": { "start": "09:00", "end": "10:00" } },
    {
      "id": "job2",
      "time_on_site": "00:10",
      "location": "39.597111, -105.041015",
      "time_window": { "start": "09:00", "end": "10:00" },
      "time_window2": { "start": "12:00", "end": "13:00" }
    }, {
      "id": "job3",
      "time_on_site": "00:10",
      "location": "39.727919,-105.103126",
      "time_window": { "start": "02:00", "end": "03:00" },
      "time_window2": { "start": "08:00", "end": "10:00" }
    }
  ]
}

The routing_with_time_windows_build.json build request - download it here. Click here to open it in the UI.

routing_with_time_windows_build.json has four jobs.
job0 has no time window, so will be routed at the most efficient time.
job1 will be delivered between 9:00 AM and 10:00 AM.
job2 can either be delivered between 9:00 AM and 10:00 AM or between 12:00 PM and 1:00 PM. Because job1 and job3 have to be delivered before 10:00 AM, job2 will most likely be delivered between 12:00 PM and 1:00 PM.
job3 can either be delivered between 2:00 AM and 3:00 AM or between 8:00 AM and 10:00 AM. Because the first time window is before the shift starts, the job will be delivered between 8:00 AM and 10:00 AM.

Response

{
  "routes": [
    {
      "id": "route0",
      "stops": [
        { "type": "depot", ... },
        { "id": "job3", "arrival_time": "09:15:36", "time_on_site": "00:10:00", ... },
        { "id": "job1", "arrival_time": "09:40:02", "time_on_site": "00:10:00", ... },
        { "id": "job0", "arrival_time": "10:00:38", "time_on_site": "00:10:00", ... },
        { "id": "job2", "arrival_time": "12:00:00", "time_on_site": "00:10:00", "idle_time": "01:38:12", ... },
        { "type": "depot", ... }
      ]
    }
  ],
  "unrouted_jobs": []
}

A snipped version of the build response - download a copy here. Click here to open it in the UI.

job3 and job1 are routed before 10:00 AM, ensuring their time windows are obeyed. Because job1 finishes at 9:50 AM, job2 cannot be routed during its morning time window, so the driver has to idle until its 12:00 PM time window opens. job0 is routed during this wait time, but there is still "idle_time": "01:38:12" before job2. The idle_time field is only shown for jobs with idle time.

Over-midnight Time Windows

Time windows which span midnight can be specified as follows:

{
  "id": "job0",
  "location": "39.635928, -105.049219",
  "time_window": { "start": "23:00", "end": "25:00" }
}

A time window between 11:00 PM and 1:00 AM.

Violations

If the time_windows_as_hard_constraint settings flag is set to false, then RouteCloud may allow a driver to violate a jobs time_window constraint in order to route more stops. By default, time_windows_as_hard_constraint is set to true.

{
  "routes": [ ... ],
  "jobs": [ ... ],
  "settings": {
    "time_windows_as_hard_constraint": false
  }
}

Time windows as a soft constraint.

Jobs that violate their time window receive a job_missed_time_window violation on their stop response object:

{
  "type": "job",
  "id": "job1",
  "arrival_datetime": "2016-01-18T00:26:58",
  "time_on_site": "00:00:00",
  "distance_to_meters": 19440.0,
  "time_to": "00:26:58"
  "violations": [
    { "type": "job_missed_time_window" }
  ]
}
Note

If time windows are set as a hard constraint, build requests should never produce a job_missed_time_window violation violation, but sequence, recommend, and evaluate requests may.

See Also