--- metadata: - name: generator content: Diplodoc Platform v5.64.0 alternate: - https://yandex.ru/routing/doc/en/calendar/properties-options.md - https://yandex.ru/routing/doc/ru/calendar/properties-options.md - href: https://yandex.ru/routing/doc/en/calendar/properties-options.md type: text/markdown title: Markdown version - href: https://yandex.ru/routing/doc/en/llms.txt?revision=r21872121 rel: describedby title: RouteQ — Calendar Planning — global options --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/routing/doc/en/llms.txt?revision=r21872121 # Global options Global options set general Calendar Planning parameters that apply to all locations and all employees. Note that parameters for a [specific location](https://yandex.ru/routing/doc/en/calendar/properties-locations.md) or [specific employee](https://yandex.ru/routing/doc/en/calendar/properties-employees.md) 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 {#planning} 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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to specify the time zone. {% note alert %} GMT and Etc/GMT are two different ways to specify a time zone. For example, GMT+1 corresponds to Etc/GMT-1. {% endnote %} ## Solution quality {#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 {#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](https://yandex.ru/routing/doc/en/calendar/properties-employees.md#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. {% note info %} The `working_days` parameter has a higher priority than `working_days_in_week`: if the `working_days` parameter is specified, `working_days_in_week` is ignored. If all three parameters (`working_days_in_week`, `working_days`, and `non_working_days`) aren't specified, all weekdays are considered working days. {% endnote %} 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 {#options-visitors} 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 {#multiorders} 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. {% note tip %} To get the optimal solution to a calendar planning task, set the `per_partially_visited` penalty value slightly higher than `per_extra_visit`, but don't set it too high. {% endnote %} Default penalty values are 0. Locations are merged only if other restrictions aren't violated, for example, [the locations' tag compatibility](https://yandex.ru/routing/doc/en/calendar/properties-locations.md#load-types). ## Moving between start and end route points on neighboring days {#duration-start-end} 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. {% note 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. {% endnote %} * 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 {#early-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](https://yandex.ru/routing/doc/en/calendar/use-cases.md#priority). 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](https://yandex.ru/routing/doc/en/calendar/use-cases.md#early-days). ## Post-optimization {#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