Instantiate

The instantiate call generates new empty routes using a collection of drivers and shift_patterns, and new jobs using a collection of recurring schedules. The routes and jobs generated by the instantiate call can then be used in a build routes call.

Query Parameters

  • start_date=YYYY-MM-DD - Required. The first day of empty route generation.
  • num_days= - Optional. The number of days that empty routes are generated for. If not provided, routes are generated for one day.
  • generate_routes=0 - Optional. If provided, no routes are generated from shift_patterns. This is useful if only jobs are required.
  • generate_jobs=0 - Optional. If provided, no jobs are generated from schedules. This is useful if only routes are required.

Status Codes

instantiate_request

The instantiate_request type inherits all fields from problem.

Name Type Description
custom custom Inherited. User-supplied custom fields that are returned unmodified in the response. These have no effect on optimization.
drivers driver[] Inherited. The drivers for whom routes are instantiated. Drivers should specify at least one shift_pattern in order for routes to be generated.
id string Inherited. An identifier for the request. See Request IDs.
jobs job[] Inherited. Any jobs that have already been created. When instantiating, if a job already exists for a particular ordinal of a schedule, a new job is not created for that ordinal.
name string Inherited. A name for the request. See Request IDs.
return_request boolean Optional. Defines if the the original request, with calculated values, is returned as the response. If not, an Instantiate Response is returned. See Full vs Partial Responses. Defaults to false.
routes route[] Inherited. Any routes that have already been created, empty or otherwise. When instantiating, if a driver's shift intersects with any existing route, a new route is not generated for the shift.
schedules schedule[] Inherited. The schedules that are involved in this instantiation. Schedules define a recurring pattern from which jobs are instantiated.
settings settings Inherited. The settings that will be applied during a subsequent build of the generated routes. The defaults field is important. This field is used in this request to ensure that the generated routes do not overlap.
shift_overrides shift_override[] Optional. The shift overrides that are involved in this problem. Shift overrides define one-off deviations from the work specified by a shift_pattern.
shift_patterns shift_pattern[] Inherited. The shift patterns that are involved in this instantiation. Shift patterns define the day-by-day ordering of shifts for a driver.
shifts shift[] Inherited. The shifts that are involved in this instantiation. Shifts contain all the information necessary to generate a route. 
{
  "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": "three_day_pattern",
      "shifts": [ ["shift0"], ["shift1"], [] ]
    }
  ],
  "drivers": [
    {
      "id": "driver0",
      "shift_patterns": [ { "shift_pattern": "shiftpattern0", "start_date": "2017-10-02" } ]
    },
    {
      "id": "driver1",
      "shift_patterns": [ { "shift_pattern": "shiftpattern0", "start_date": "2017-10-03", "end_date": "2017-10-03" } ]
    }
  ],
  "schedules": [
    {
      "id": "schedule0",
      "earliest_date": "2017-10-01",
      "base_date": "2017-10-01",
      "type": "daily",
      "interval": 2,
      "job_template": {
        "location": "-43.549062, 172.642059"
      }
    }
  ]
}

An example instantiate request.

instantiate_response

Note

The result of an instantiate call is a problem instead of an instantiate_response, if return_request was set to true on the input.

The instantiate_response type contains information about the routes and jobs that were instantiated.

{
  "routes": [
    {
      "id": "e9dbd154-2c78-4732-9383-b4139e72313a",
      "name": "Oct 2 - driver0 - morning_shift",
      "driver": "driver0",
      "date": "2017-10-02T00:00:00",
      "start_time": "01:00:00",
      "end_time": "10:00:00"
    },
    {
      "id": "0a17956b-5486-4c5a-9393-88d3bb1b5440",
      "name": "Oct 3 - driver0 - afternoon_shift",
      "driver": "driver0",
      "date": "2017-10-03T00:00:00",
      "start_time": "13:00:00",
      "end_time": "22:00:00"
    },
    {
      "id": "aea284d3-f9b6-4fdc-95a3-dad89c043dd9",
      "name": "Oct 3 - driver1 - morning_shift",
      "driver": "driver1",
      "date": "2017-10-03T00:00:00",
      "start_time": "01:00:00",
      "end_time": "10:00:00"
    },
    {
      "id": "4cc969fc-3db1-4155-936a-76d5d7107933",
      "name": "Oct 5 - driver0 - morning_shift",
      "driver": "driver0",
      "date": "2017-10-05T00:00:00",
      "start_time": "01:00:00",
      "end_time": "10:00:00"
    }
  ],
  "schedules": [
    {
      "id": "schedule0",
      "jobs": [
        {
          "ordinal": 1,
          "job": "23df764e-c2c1-4246-9bb4-258440da85b5",
          "target_date_range": {
            "from_date": "2017-10-03",
            "num_days": 1
          },
          "target_date": "2017-10-03"
        },
        {
          "ordinal": 2,
          "job": "53357e41-d7cc-4ffe-b9ce-1c4a5eb68dd7",
          "target_date_range": {
            "from_date": "2017-10-05",
            "num_days": 1
          },
          "target_date": "2017-10-05"
        }
      ]
    }
  ],
  "jobs": [
    {
      "id": "23df764e-c2c1-4246-9bb4-258440da85b5",
      "name": "schedule0 [1]",
      "location": "-43.549062,172.642059"
    },
    {
      "id": "53357e41-d7cc-4ffe-b9ce-1c4a5eb68dd7",
      "name": "schedule0 [2]",
      "location": "-43.549062,172.642059"
    }
  ]
}

An example instantiate response, with start_date=2017-10-02 and num_days=4.

See Also