--- 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/ru/calendar/properties-options.md type: text/markdown title: Markdown version - href: https://yandex.ru/routing/doc/ru/llms.txt?revision=r21872121 rel: describedby title: Яндекс Маршрутизация — Календарное планирование — глобальные опции --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/routing/doc/ru/llms.txt?revision=r21872121 # Глобальные опции Глобальные опции задают общие параметры Календарного планирования, которые действуют на все локации и всех сотрудников. Однако параметры для [конкретной локации](https://yandex.ru/routing/doc/ru/calendar/properties-locations.md) или [конкретного сотрудника](https://yandex.ru/routing/doc/ru/calendar/properties-employees.md), как правило, имеют более высокий приоритет. При планировании с помощью Excel глобальные параметры задаются на листе `options`, при планировании в API — в объекте `options`. ## Период планирования {#planning} Начальная дата периода планирования указывается в параметре `date` в формате `YYYY-MM-DD` (по умолчанию равна текущей дате), длительность периода планирования — в параметре `planning_days` в днях. Относительные временные окна рассчитываются в часовом поясе, который задается при помощи параметра `options.time_zone`. Поле `time_zone` является обязательным. При планировании через API есть два варианта указания часового пояса: - как число от -12 до 14, которое определяет сдвиг по отношению к UTC в часах. Например, 3 соответствует GMT+3 (Москва). - как строка. Например, `Europe/Moscow`. При планировании с помощью Excel часовой пояс задается только как число. При определении часового пояса используйте [список часовых поясов](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). {% note alert %} GMT и Etc/GMT — это два разных варианта определения часового пояса. Например, GMT+3 соответствует Etc/GMT-3. {% endnote %} ## Качество решения {#quality} При построении маршрутов сервис выбирает оптимальный вариант маршрутизации. Алгоритм строит решение таким образом, чтобы его стоимость была минимальной. При планировании через API качество решения задается при помощи параметра `options.quality`. Возможные значения: - `low` — отладочный режим. Используется только для проверки заданных ограничений (убедиться, что нет логических ошибок, введены верные исходные данные и т.п.). Преимущество настройки — небольшое время выполнения планирования. Анализировать маршруты, которые были построены в отладочном режиме, нельзя. - `normal` — базовое качество решения. Является значением по умолчанию. Этой настройки достаточно для выполнения большинства задач маршрутизации. ## Рабочие и нерабочие дни {#working-days} Рабочие и нерабочие дни могут задаваться: - для конкретного сотрудника — в Excel на листе `working_days` в поле `working_days` (`employees.working_days.day` в API). Подробнее см. раздел [Рабочие и нерабочие дни сотрудника](https://yandex.ru/routing/doc/ru/calendar/properties-employees.md#working-days); - для всех сотрудников — на листе `options` в полях `working_days` и `non_working_days` (`options.working_days` и `options.non_working_days` в API). Если задан `non_working_days`, то эти дни вычитаются из рабочих дней. Общее число рабочих дней в неделе задается на листе `options` в поле `working_days_in_week` (не больше 7). Рабочие дни всегда начинаются с понедельника и распределяются по неделе непрерывно, оставшиеся дни недели считаются нерабочими. По умолчанию `working_days_in_week` = 5, это соответствует обычной пятидневной рабочей неделе. {% note info %} Параметр `working_days` приоритетнее `working_days_in_week` — если задан `working_days`, то `working_days_in_week` игнорируется. Если все три параметра `working_days_in_week`, `working_days` и `non_working_days` не указаны, то рабочими считаются все будние дни. {% endnote %} Другие примеры значений: - `working_days_in_week` = 7 — все дни будут рабочими. Также указывайте значение 7, когда суббота выходной, а воскресенье — рабочий день; - `working_days_in_week` = 6 — соответствует шестидневной рабочей неделе, когда суббота рабочая; - `working_days_in_week` = 2 — рабочими днями будут только понедельник и вторник. Если рабочие дни указаны и для конкретного сотрудника, и для всех сотрудников в целом, то рабочими будут считаться дни, общие для обоих параметров. Например: #| || **options.working_days** | **working_days.working_days** | **Рабочие дни** || || Mon, Tue, Wed | Tue, Fri | Tue || || Mon, Tue, Wed | Tue, Wed | Tue, Wed || || Mon, Tue, Wed | Thu, Fri | Нет рабочих дней || |# ## Продление рабочих дней до максимальной продолжительности смены {#shift-duration-extend-all} Вы можете продлить рабочие дни до максимальной продолжительности смены: - для конкретного сотрудника — в Excel на листе `working_days` в поле `extend_to_max_duration` (`employees.working_days.extend_to_max_duration` в API). Подробнее см. в разделе [Продление рабочего дня до максимальной продолжительности смены](https://yandex.ru/routing/doc/ru/calendar/properties-employees.md#shift-duration-extend); - для всех сотрудников — на листе `options` в поле `extend_all_days_to_max_duration` (`options.extend_all_days_to_max_duration` в API). Параметр `extend_to_max_duration` приоритетнее `extend_all_days_to_max_duration`. Если вы задали `extend_all_days_to_max_duration` = `true`, а для конкретного дня указали `extend_to_max_duration` = `false`, алгоритм не продлит этот день. {% note info %} Чтобы опция `extend_all_days_to_max_duration` работала, обязательно на листе **working_days** укажите значение параметра `max_duration_s`. {% endnote %} **Пример 1** В планировании участвуют два сотрудника и 15 локаций. На листе **working_days** (в объекте `employees.working_days` в API) вы указали для сотрудников: - рабочие дни — `day` = `Mon, Tue, Wed, Thu, Fri`; - время начала смен — `start_time` = `09:00-09:00`; - продолжительность смен — `max_duration_s` = 14 400. В результате планирования все локации назначаются сотруднику 2, так как ограничение продолжительности смены `max_duration_s` нестрогое. Он начинает маршрут в 09:00 и заканчивает в 17:17. [Пример Excel](https://doc-static.yandex.net/src/dev/routing/calendar-examples/shift-duration-extend-all-1.xlsx) ⋅ [Запрос API (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/01a155b5-c39e-867b-a6dc-f1bacdb31b00) ⋅ [Ответ API](https://courier.yandex.ru/vrs/api/v1/result/01a155b5-c39e-867b-a6dc-f1bacdb31b00) **Пример 2** Те же условия, что в примере 1, но на листе **options** вы указали `extend_all_days_to_max_duration` = `true` (`employees.working_days.extend_all_to_max_duration` = `true` в API). В результате планирования: - сотрудник 1 начинает маршрут в 09:00 и заканчивает в 17:17 — длительность его смены превышает продолжительность в 14 400 секунд, которую вы установили в параметре `max_duration_s`; - сотрудник 2 не посещает локации, но присутствует на смене с 09:00 до 13:00. [Пример Excel](https://doc-static.yandex.net/src/dev/routing/calendar-examples/shift-duration-extend-all-2.xlsx) ⋅ [Запрос API (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/01a155bb-dfbc-8241-a312-cd3a5bbe0d00) ⋅ [Ответ API](https://courier.yandex.ru/vrs/api/v1/result/01a155bb-dfbc-8241-a312-cd3a5bbe0d00) ## Сотрудники, посещающие локацию {#options-visitors} По умолчанию локацию должен посещать один и тот же сотрудник. Если это условие не важно для планирования, включите опцию `allow_multiple_visitors` = `true`, тогда в разные дни локацию смогут посещать разные сотрудники. ## Адреса с несколькими локациями {#multiorders} Несколько локаций могут находиться по одному адресу (например, несколько магазинов в одном торговом центре). Чтобы запланировать посещение таких локаций за один приезд, в файле Excel на листе `options` можно указать штрафы: * `penalty.multiorders.per_extra_point` — штраф за каждый адрес, на который сотрудники приезжают больше одного раза; * `penalty.multiorders.per_extra_employee` — штраф за каждого лишнего сотрудника, который посещает адрес с несколькими локациями (если посещения запланированы на нескольких сотрудников); * `penalty.multiorders.per_extra_visit` — штраф за каждое лишнее посещение адреса с несколькими локациями; * `penalty.multiorders.per_partially_visited` — штраф за каждую локацию, которая посещена не полностью (или совсем не посещена), при условии, что близкие к ней локации были посещены; * `penalty.multiorders.per_dropped` — штраф за каждую локацию, которая не посещена, при условии, что близкие к ней локации были посещены. {% note tip %} Чтобы получить наиболее оптимальное решение задачи календарного планирования, задайте значение штрафа `per_partially_visited` немного выше, чем `per_extra_visit`, но не завышайте его. {% endnote %} Значения штрафов по умолчанию равны 0. Объединение локаций выполняется, только если при этом не нарушаются другие ограничения — например, [совместимость локаций по тегам](https://yandex.ru/routing/doc/ru/calendar/properties-locations.md#load-types). ## Перемещения между начальными или конечными точками маршрутов соседних дней {#duration-start-end} При планировании может получаться так, что в разные дни сотрудник обслуживает локации, расположенные далеко друг от друга. В начале каждого дня сотруднику может потребоваться переместиться за сотни километров от своей начальной позиции в предыдущий день. Чтобы избежать таких ситуаций, можно прибавлять к стоимости маршрута протяженность или длительность перемещений между начальными точками маршрутов в соседние дни. Ограничения можно настроить следующими способами: * с помощью коэффициентов: * Параметры `duration_between_days_starts_factor` и `distance_between_days_starts_factor` задают коэффициенты, на которые умножается стоимость перемещений к начальной точке дневного маршрута. По умолчанию параметры имеют значение 0. Если они заданы как 1, эти перемещения будут считаться так же, как если бы они были частью маршрута (с той же стоимостью за час и км). * Параметры `duration_between_days_ends_factor` и `distance_between_days_ends_factor` задают аналогичные ограничения для перемещений между конечными точками маршрутов в соседние дни. {% note alert %} Рекомендуемый диапазон значений параметров — от 0 до 1. Значения больше 1 приводят к построению неоптимальных маршрутов и увеличению общего километража. {% endnote %} * с помощью абсолютных величин: * `between_days_max_edge_duration_s` — максимальная длительность перемещения в секундах между последней локацией дня и первой локацией следующего дня; * `between_days_max_edge_distance_m` — максимальное расстояние в метрах между последней локацией дня и первой локацией следующего дня. ## Посещения в наиболее ранние дни {#early-days} Параметр `late_days_cost_increment` позволяет планировать посещения выбранных локаций в более ранние дни. Его можно использовать самостоятельно или вместе с указанием [приоритетов локаций](https://yandex.ru/routing/doc/ru/calendar/use-cases.md#priority). При использовании `late_days_cost_increment` к стоимости каждого дня прибавляется значение параметра, умноженное на номер дня, начиная с 0. Так, к первому дню ничего не прибавляется, ко второму прибавляется `late_days_cost_increment`, к третьему `2 * late_days_cost_increment` и т.д. Влияние этого параметра постепенно убывает благодаря внутреннему коэффициенту, который снижается от 1 до 0 в процессе оптимизации. Поэтому финальная стоимость решения не изменяется. Пример использования параметра см. в разделе [Посещение в наиболее ранние дни](https://yandex.ru/routing/doc/ru/calendar/use-cases.md#early-days). ## Пост-оптимизация {#post-optimization} При использовании параметра `post_optimization` = `true` оптимизация запускается на 90% времени, а остальные 10% занимает повторный запуск алгоритма, в котором осуществляется пост-оптимизация. Пост-оптимизация может улучшить решение, если в задаче используются параметры кучности `daily_proximity_factor` или `global_proximity_factor`. В этом случае маршрут будет перестраиваться и группироваться вокруг локации, которая была последней в этом маршруте до пост-оптимизации. ## Отдельные приоритеты для каждого сотрудника {#per-employee-priority} Значение опции `per_employee_priority` определяет, как применяются [приоритеты](https://yandex.ru/routing/doc/ru/calendar/properties-locations.md#priority) при планировании: * `false` (по умолчанию) — глобально для всего решения; * `true` — для каждого сотрудника по отдельности. Если опция включена, у локаций должно быть заполнено поле [`employee_id`](https://yandex.ru/routing/doc/ru/calendar/properties-locations.md#employee-id). Написать в службу поддержки