Global options

Global options set general Calendar Planning parameters that apply to all locations and all employees. Note that parameters for a specific location or specific employee usually have a higher priority.

When planning with Excel, global parameters are set on the options sheet. When planning via the API, global parameters are set in the options object.

Planning period

The planning period start date is specified in the date parameter in YYYY-MM-DD format (by default, equals the current date). The planning period duration is specified in the planning_days parameter in days.

Relative time windows are calculated in the time zone that is set with the options.time_zone parameter. The time_zone field is mandatory.

When planning via the API, there are two ways to specify the time zone:

• As a number between -12 and 14 that determines the offset relative to UTC in hours. For example, 1 corresponds to GMT+1 (London).

• As a string. For example, Europe/London.

When planning with Excel, the time zone is set only as a number.

Use a list of time zones to specify the time zone.

Solution quality

When building routes, the service selects the optimal routing option. The algorithm builds the solution so that its cost is minimal.

When planning via the API, the quality of the solution is set using the options.quality parameter. Possible values:

• low: Debug mode. It is used only to check the specified restrictions (to make sure that there are no logical errors, correct source data is entered, and other activities). The advantage of the setting is a short planning time. You can't analyze the routes built in debug mode.

• normal: Basic quality of the solution. It is the default value. This setting is sufficient to perform the majority of routing tasks.

Working and non-working days

You can specify working and non-working days:

• For a particular employee: in the working_days field on the working_days Excel sheet (employees.working_days.day in the API). To learn more, see Employee's working and non-working days.
• For all employees: in the working_days and non_working_days fields on the options sheet (options.working_days and options.non_working_days in the API). If the non_working_days parameter is specified, those days are subtracted from working days.

The total number of working days per week is specified in the working_days_in_week field (no more than 7) on the options sheet. Working days always start on Monday and are distributed continuously throughout the week. The remaining days are considered non-working days. By default, working_days_in_week = 5, which corresponds to a normal 5-day working week.

Other sample values:

• working_days_in_week = 7: All days are working days. Also set the parameter to 7 when Saturday is a non-working day and Sunday is a working day.
• working_days_in_week = 6: Corresponds to a 6-day working week, where Saturday is a working day.
• working_days_in_week = 2: Only Monday and Tuesday are working days.

If working days are specified both for a particular employee and all employees in general, days that are common for both parameters are considered working days. For example:

options.working_days	working_days.working_days	Working days
Mon, Tue, Wed	Tue, Fri	Tue
Mon, Tue, Wed	Tue, Wed	Tue, Wed
Mon, Tue, Wed	Thu, Fri	No working days

Employees who visit a location

By default, one location must be visited by the same employee. If this condition isn't important for planning, set allow_multiple_visitors to true to allow different employees to visit the same location on different days.

Addresses with multiple locations

Multiple locations can be at the same address (for example, there's a shopping center with multiple stores). To handle such locations within a single visit, you can set penalties on the options sheet in the Excel file:

• penalty.multiorders.per_extra_point: Penalty for each address employees visit more than once.
• penalty.multiorders.per_extra_employee: Penalty for each extra employee who visits an address with multiple locations (if visits are planned for multiple employees).
• penalty.multiorders.per_extra_visit: Penalty for each extra visit to an address with multiple locations.
• penalty.multiorders.per_partially_visited: Penalty for each location that was not fully visited (or not visited at all), provided that nearby locations were visited.
• penalty.multiorders.per_dropped: Penalty for each location that was not visited, provided that nearby locations were visited.

Default penalty values are 0.

Locations are merged only if other restrictions aren't violated, for example, the locations' tag compatibility.

Moving between start and end route points on neighboring days

When planning, it may turn out that an employee handles locations that are far away from each other on different days. At the start of each day, an employee may need to travel hundreds of kilometers from their starting position on the previous day. To avoid such situations, you can take the distance or duration of transit between the starting route points on neighboring days and add it to the route cost.

You can configure restrictions in the following ways:

• Using factors:

  • The duration_between_days_starts_factor and distance_between_days_starts_factor parameters set the factors by which the cost of travels to the starting point of the day's route is multiplied. The default values are 0. If the values are 1, the travels are considered a part of the route (with the same cost per hour and km).

  • The duration_between_days_ends_factor and distance_between_days_ends_factor parameters impose similar restrictions for travels between end points of routes on neighboring days.

  Alert

  The recommended range of parameter values is from 0 to 1. Values greater than 1 result in suboptimal routes and an increase in total mileage.

• Using absolute values:

  • between_days_max_edge_duration_s: Maximum duration of travel between the last location of the day and the first location of the next day, in seconds.

  • between_days_max_edge_distance_m: Maximum distance between the last location of the day and the first location of the next day, in meters.

Visits on the earliest days

The late_days_cost_increment parameter allows planning visits to selected locations on earlier days. It can be used independently or together with location priorities.

When using late_days_cost_increment, the parameter value multiplied by the day number starting from 0 is added to each day's cost. Thus, nothing is added to the first day, late_days_cost_increment is added to the second day, 2 * late_days_cost_increment is added to the third day, and so forth. The impact of this parameter gradually decreases due to an internal factor that goes down from 1 to 0 during optimization. As a result, the solution's final cost doesn't change.

For an example of using this parameter, see Visits on the earliest days.

Post-optimization

With post_optimization set to true, the optimization runs 90% of the time, and the remaining 10% are taken up by re-running the algorithm where post-optimization is performed.

Post-optimization can improve the solution if the task uses the daily_proximity_factor or global_proximity_factor density parameters. In this case, the route is rebuilt and grouped around its last location prior to post-optimization.

Contact support