API – time windows

This page describes advanced features of OptiFacility related to availability time windows. Before reading this section, ensure you have read about basic features of OptiFacility.

The following json file defines an instance of the problem with time windows constraints. Additions to the basic json file are highlighted:

{
    "UserID": "demo",
    "RequestID": 12347,
    "Comment": "my first request with time window constraints",
    "Quality": 2,
    "AgentSpeed": 45.0,
    "AgentWorkTime": 12.0,
    "AgentVisitTime": 1.0,
    "AgentStartTime": 6.0,
    "CostAgentWork1h": 70.0,
    "CostAgentTravel1km": 1.0,
    "Facilities": [{"Lat":51.929, "Lon":18.615, "TimeConstraints":[{"From":0.0,"To":16.0}]},
                   {"Lat":52.039, "Lon":18.765, "TimeConstraints":[{"From":18.0,"To":20.0}]},
                   {"Lat":51.874, "Lon":18.971, "TimeConstraints":[{"From":35.2,"To":37.4}]},
                   {"Lat":52.058, "Lon":19.177, "TimeConstraints":[{"From":10.0,"To":13.0},
                                                                   {"From":14.0,"To":17.0}]},
                   {"Lat":51.99,  "Lon":18.589},
                   {"Lat":51.865, "Lon":18.765},
                   {"Lat":51.89,  "Lon":19.098},
                   {"Lat":52.014, "Lon":18.89},
                   {"Lat":52.011, "Lon":19.237}],
    "Agents": [{"Lat":51.768, "Lon":19.094,  "AgentStartTime": 9.0}],
    "Task": "FindRoutesCommutingIncluded"
}

The meaning of the highlighted fields is explained below:

• AgentStartTime – optional field: time of day (in hours) when an agent starts their work. This value will be set as a default value for all agents in this instance. If not defined, the default value will be set to 9.0.
• Facilities: TimeConstraints – an array of objects defining time windows in which the facility can be visited. The facility needs to be visited only within one of the time windows, not all of them. Each time window object consists of two values: "From" and "To". "From" value defines the earliest moment when an agent can start the visit, while "To" value defines the latest moment when an agent can finish the visit. This means that if the time between "To" and "From" is shorter than the value of "AgentVisitTime", no agent can visit such a facility during such a time window.

  Time windows must be defined in chronological order, and must not overlap. Facilities without defined time constraints can be visited at any point in time.

• Agents: AgentStartTime – optional field: time of day (in hours) when a particular agent starts their work. This value overwrites the default one.

Time values in "TimeConstraints" are defined relative to 0.0 which is the midnight (the beginning) of the first day. A value of 17.25 means 17:15 (5:15pm). A value of 30.5 means the second day, 6:30am (1*24.0 + 6.5).

Time windows can be used to represent deadlines. To use time windows for this purpose, the "From" value should be set to 0.0, while the "To" value should be set to the actual deadline time. Time windows can be longer than 24 hours.