Routing with Dates

It is possible to specify date fields on routes, and use these to constrain the jobs that a route can service.

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",
      "date": "2016-1-18"
    }, {
      "id": "route1",
      "location": "39.718005, -104.969531",
      "date": "2016-1-19"
    }, {
      "id": "route2",
      "location": "39.718005, -104.969531",
      "date": "2016-1-20"
    }
  ],
  "jobs": [
    { "id": "job0", "location": "39.635928, -105.049219" },
    { "id": "job1", "location": "39.725375, -104.791080", "date": "2016-1-18" },
    { "id": "job2", "location": "39.708990, -105.026954", "date": "2016-1-19" },
    { "id": "job3", "location": "39.653975, -105.093750", "allowed_dates": [ "2016-1-18", "2016-1-19" ] },
    { "id": "job4", "location": "39.590789, -105.084376", "allowed_dates": [ "2016-1-20" ] },
    { "id": "job5", "location": "39.590789, -105.084376", "allowed_dates": [ ] }
  ]
}

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

routing_with_dates_build.json specifies three routes, each on different days, and six jobs, each with different date constraints.
job0 has no date constraints, and so can be placed on any route.
job1 must be completed on January 18, so can only be placed on route0.
job2 must be completed on January 19, so can only be placed on route1.
job3 can be completed on either January 18 or 19, so can be placed on either route0 or route1.
job4 must be completed on January 20, so can only be placed on route2.
job5 has an empty array of allowed_dates, so cannot be placed on any routes and will not be routed.

Note

When building routes, if any job has a date or allowed_dates field set, then all routes must have a date field. Similarly, if any route has a date field, then all other routes must also have a date field.

Response

{
  "routes": [
    {
      "id": "route0",
      "cost": 13.52,
      "internal_cost": 121.76,
      "distance_meters": 38810.0,
      "working_time": "00:54:04",
      "driving_time": "00:54:04",
      "stops": [
        {
          "location": "39.718005,-104.969531",
          "type": "depot",
          "arrival_datetime": "2016-01-18T00:00:00",
          "time_on_site": "00:00:00",
          "distance_to_meters": 0.0,
          "time_to": "00:00:00"
        },
        {
          "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"
        },
        { "type": "depot", ... }
      ]
    }, {
      "id": "route1", ...
      "stops": [ { "type": "depot", ... }, { "id": "job3", ... }, { "id": "job2", ... }, { "type": "depot", ... } ]
    }, {
      "id": "route2", ...
      "stops": [ { "type": "depot", ... }, { "id": "job0", ... }, { "id": "job4", ... }, { "type": "depot", ... } ]
    }
  ],
  "unrouted_jobs": [
    { "id": "job5" }
  ]
}

Snipped build response - download a full copy from here. Click here to open it in the UI.

Note

stops now have an arrival_datetime instead of an arrival_time. Route responses are unchanged.

Violations

If a job is placed on a disallowed day, then a job_delivered_on_disallowed_day violation is generated:

{
  "type": "job",
  "id": "job0",
  "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_delivered_on_disallowed_day" }
  ]
}
Note

build requests should never produce a job_delivered_on_disallowed_day violation, but sequence, recommend, and evaluate requests may.

See Also