Instantiating Routes

The RouteCloud API can be used to instantiate empty routes for drivers based on their shift_patterns. To instantiate routes, POST an instantiate_request in JSON format to /v1/instantiate, including a start date and number of days as query parameters. For every driver in the request, the RouteCloud API generates an empty route for each of the driver's shifts that fall within the date range, provided they do not intersect with any other routes in the request.

Note that Instantiating Jobs can be done in the same request as instantiating routes.

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.

You can download a copy of the instantiate_request.json example instantiate request from here. Run the request in the command line using cURL:

curl -u "youraccount%3Amain:password" "https://routecloud.telogis.com/v1/instantiate?start_date=2017-10-01&num_days=7" -H "Content-Type: application/json" --data-binary "@instantiate_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 RouteCloud API will generate routes and should return a response within a few seconds.

Request

{
  "id": "request-1234567",
  "name": "instantiate_request",
  "shifts": [
    { "id": "shift0", "name": "morning_shift", "start_time": "01:00", "end_time": "10:00" },
    { "id": "shift1", "name": "afternoon_shift", "start_time": "13:00", "end_time": "22:00" }
  ],
  "shift_patterns": [
    {
      "id": "shiftpattern0",
      "name": "weekly_pattern",
      "shifts": [
        ["shift0"],
        ["shift0"],
        ["shift0", "shift1"],
        ["shift1"],
        ["shift1"],
        [],
        []
      ]
    }
  ],
  "shift_overrides": [
    {
      "start_date": "2017-10-04",
      "end_date": "2017-10-04"
    }
  ],
  "drivers": [
    {
      "id": "driver0",
      "shift_patterns": [
        {
          "shift_pattern": "shiftpattern0",
          "start_date": "2017-10-02"
        }
      ],
      "shift_overrides": [
        {
          "start_date": "2017-10-06",
          "end_date": "2017-10-06",
          "shift": "shift0"
        }
      ]
    },
    {
      "id": "driver1",
      "shift_patterns": [
        { "shift_pattern": "shiftpattern0", "start_date": "2017-10-04", "end_date": "2017-10-06" }
      ]
    }
  ]
}

The instantiate_request.json request. Click here to open it in the UI.

The request JSON consists of an array of shifts, an array of shift_patterns, and an array of drivers. The request also specifies a shift_override on the problem as well as one for driver0. The shifts and shift patterns are used to generate empty routes for each driver.

The request defines two shifts:

  • A morning shift, running from 1:00 AM to 10:00 AM.
  • An afternoon shift, running from 1:00 PM to 10:00 PM.

The request defines a shift pattern with a period of seven days, where:

  • The morning shift is worked for the first two days.
  • Both the morning and afternoon shifts are worked on the third day.
  • The afternoon shift is worked on the fourth and fifth days.
  • The sixth and seventh days are not worked.

The request defines a single problem-level shift_override, specifying that no shift will be worked on October 4.

The request defines two drivers:

  • "driver0", whose shifts follow the shift pattern starting on a Monday.
    • "driver0" also defines a shift_override, specifying that they will work the morning shift on October 6.
  • "driver1", whose shifts follow the shift pattern starting on a Wednesday and running until the Friday.

Since driver0's shift pattern assignment starts on a Monday, they will work Monday to Friday and have Saturday and Sunday off. Since driver1's shift pattern assignment starts on a Wednesday, they will work Wednesday to Sunday and have Monday and Tuesday off. In this case however driver1's shift pattern assignment ends on the Friday, meaning they only work for three days.

Response

{
  "routes": [
    { "name": "Oct 2 - driver0 - morning_shift", "start_time": "01:00:00", "end_time": "10:00:00", ... },
    { "name": "Oct 3 - driver0 - morning_shift", "start_time": "01:00:00", "end_time": "10:00:00", ... },
    { "name": "Oct 5 - driver0 - afternoon_shift", "start_time": "13:00:00", "end_time": "22:00:00", ... },
    { "name": "Oct 5 - driver1 - morning_shift", "start_time": "01:00:00", "end_time": "10:00:00", ... },
    { "name": "Oct 6 - driver0 - morning_shift", "start_time": "01:00:00", "end_time": "10:00:00", ... },
    { "name": "Oct 6 - driver1 - morning_shift", "start_time": "01:00:00", "end_time": "10:00:00", ... },
    { "name": "Oct 6 - driver1 - afternoon_shift", "start_time": "13:00:00", "end_time": "22:00:00", ... }
  ]
}

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

The response object consists of an array of empty route objects. Each route has been assigned a driver and a date, and has a copy of the details from the shift; for example, the start_time and end_time. The routes do not have any reference to the shifts from which they were instantiated, except for the name of the shift being included in the route's name.

Explanation:

  • driver0 begins work on Monday, October 2:
    • For the first two days, they are given Oct 2 - driver0 - morning_shift and Oct 3 - driver0 - morning_shift respectively, both starting at 1:00 AM and finishing at 10:00 AM.
    • The third day is a day off, specified by the problem-level shift override on October 4, so no route is generated.
    • For the fourth day, they are given Oct 5 - driver0 - afternoon_shift, starting at 1:00 PM and finishing at 10:00 PM.
    • For the fifth day, they are given Oct 6 - driver0 - morning_shift, since there is a shift override for this day.
    • For the sixth and seventh days, they are not given any routes as the shift pattern specifies no shifts for these days.
  • driver1 begins work on Wednesday, October 4:
    • The first day is a day off, specified by the problem-level shift override on October 4, so no route is generated.
    • For the second day, they are given Oct 5 - driver1 - morning_shift, starting at 1:00 AM and finishing at 10:00 AM.
    • For the third day, they are given Oct 6 - driver1 - morning_shift and Oct 6 - driver1 - afternoon_shift, as the shift pattern defined in the request specifies two shifts for the third day
    • No further routes are generated for driver as their shift pattern assignment ends on October 6.
  • No routes are generated after October 8 as the num_days query parameter was set to 7. If num_days were greater than 7, driver0 would be given additional routes based on the shift pattern looping back to the beginning; for example, Oct 9 - driver0 - morning_shift.

These routes can then have jobs assigned to them using a build request.

What Next?