Routing with Zones

A driver zone is a geographic area that is defined by a polygon-shaped boundary. You can use zones to allocate drivers to a geographic area and then enforce that jobs located inside a driver’s zone are serviced by the drivers for that zone. A driver_not_in_zone violation occurs when a job is assigned to a driver who is not allocated to the zone in which the job is geographically located.

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.720911, -104.966610", "driver": "driver0" },
    { "id": "route1", "location": "39.720911, -104.966610", "driver": "driver1" },
    { "id": "route2", "location": "39.720911, -104.966610", "driver": "driver2" }
  ],
  "jobs": [
    { "id": "job0", "time_on_site": "00:10", "location": "39.720087, -104.971803" },
    { "id": "job1", "time_on_site": "00:10", "location": "39.719598, -104.960741" },
    { "id": "job2", "time_on_site": "00:10", "location": "39.720832, -104.966683" },
    { "id": "job3", "time_on_site": "00:10", "location": "39.725003, -104.967135" }
  ],
  "drivers": [
    { "id": "driver0" },
    { "id": "driver1" },
    { "id": "driver2" }
  ],
  "zones": [
    {
      "id": "zone0",
      "boundary": {
        "vertices": [
          "39.721951, -104.972929",
          "39.718204, -104.972854",
          "39.718287, -104.966996",
          "39.721951, -104.972929"
        ]
      },
      "drivers": ["driver0"]
    },
    {
      "id": "zone1",
      "boundary": {
        "vertices": [
          "39.722008, -104.959454",
          "39.718303, -104.966299",
          "39.718154, -104.959336",
          "39.722008, -104.959454"
        ]
      },
      "drivers": ["driver1"]
    },
    {
      "id": "zone2",
      "boundary": {
        "vertices": [
          "39.719483, -104.966685",
          "39.722008, -104.963445",
          "39.721967, -104.970065",
          "39.719483, -104.966685"
        ]
      }
    }
  ]
}

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

routing_with_zones_request.json specifies three zones, three drivers, each driver has a route and four jobs.

driver0 is assigned to route0 and allocated to zone0.
driver1 is assigned to route1 and allocated to zone1.
driver2 is assigned to route2 but not allocated to any zones.

job0 is geographically located inside zone0, so can only be placed on route0 which is assigned to driver0.
job1 is geographically located inside zone1, so can only be placed on route1 which is assigned to driver1.
job2 is geographically located inside zone2, so cannot be placed on any route as zone2 does not have any allocated drivers.
job3 is geographically not located inside any zones, so will not be placed on any route.

Response

{
  "routes": [
    {
      "id": "route0", ...
      "stops": [ { "type": "depot", ... }, { "id": "job0", ... }, { "type": "depot", ... } ]
    }, {
      "id": "route1", ...
      "stops": [ { "type": "depot", ... }, { "id": "job1", }{ "type": "depot", } ]
    }, {
      "id": "route2", ...
      "stops": [ ]
    }
  ],
  "unrouted_jobs": [ { "id": "job2" } ]
}

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

Violations

If a job is geographically located inside a zone and it is placed on a route whose assigned driver is not allocated to that zone, then a driver_not_in_zone violation is generated:

{
  "type": "job",
  "id": "job1",
  "arrival_datetime": "2016-01-18T00:26:58",
  "time_on_site": "00:10:00",
  "distance_to_meters": 876.0,
  "time_to": "00:02:48",
  "violations": [
    {
      "data": {
        "attributes": {
          "string_array_data": [ "zone1" ]
        }
      },
      "type": "driver_not_in_zone"
    }
  ]
}

When routing with zones the optimizer will not assign jobs that are not located within any zone, if such a job is assigned

{
  "type": "job",
  "id": "job3",
  "arrival_datetime": "2016-01-18T00:26:58",
  "time_on_site": "00:10:00",
  "distance_to_meters": 876.0,
  "time_to": "00:02:48",
  "violations": [
    {
      "type": "job_not_in_zone"
    }
  ]
}
Note

build requests should never produce driver_not_in_zone or job_not_in_zone violations, but sequence, recommend, and evaluate requests may.

See Also