Parameter list

Basic definitions

Planning period: A period over which you plan location visits. To set a period, specify the start date and the number of days.
Employee: A mobile employee who visits locations with a certain regularity. They may travel on foot, by car, or by public transport. During planning, you can specify a common work schedule for all employees and, if needed, tailor it to specific employees by adjusting their working and non-working days, working hours, and other parameters.
Location: Points handled by a mobile employee (store, office, and others). The frequency of visits, whether they are required or not, handling time, and other parameters are specified for each location.
Visit: An employee's arrival to a location that needs to be handled. An employee may visit one location multiple times within a planning period.
Route: A sequence of visits to locations by an employee, with the indication of the estimated time of arrival, handling time, and other parameters. An employee may have multiple routes planned within a planning period.

Prerequisites for planning

If you need to solve a Calendar Planning task, the source data must contain a number of mandatory parameters.

Excel

API

If you plan routes using an Excel file, it must contain the following sheets:

locations: Parameters of locations that mobile employees visit.
employees: Parameters of mobile employees.
working_days: Employees' work schedule.
options: Route planning parameters.

An Excel file may also contain other sheets (for example, visits with the parameters of location visits).

If you plan routes via the API, the request must contain the following objects:

locations: Parameters of locations that mobile employees visit.
employees: Parameters of mobile employees.
employee.working_days: The employee's work schedule.
options: Route planning parameters.

A request may also contain other objects (for example, location.visits with location visit parameters).

The required parameters are indicated in the description below.

Location parameters

Location parameters are set on the locations sheet in Excel or in the locations object in the API request.

Basic parameters

Parameter	Description	Required
`id`	Location ID. Learn more	Yes
`title`	Location name. Learn more	No
`description`	Location description. Learn more	No
`ref`	Additional location ID. Learn more	No
`comments`	Additional information about the location. Learn more	No
`address`	Location address. Learn more	No
`phone`	Phone number. Learn more	No
`point.lat`, `point.lon`	Location coordinates: latitude and longitude. Learn more	Yes
`type`	Location type. Learn more	Yes
`service_duration_s`	Duration of a location visit in seconds. Learn more	Yes

Time windows

Parameter	Description	Required
`time_window`	Time window to visit the location in `[D.]HH[:MM[:SS]] - [D.]HH[:MM[:SS]]` format. The `time_window` and `time_windows` fields are mutually exclusive. Learn more	No
`time_windows`	Array of time windows for visiting the location. The `time_window` and `time_windows` fields are mutually exclusive. Learn more	No
`hard_time_window`	Hard time window to visit the location in `[D.]HH[:MM[:SS]] - [D.]HH[:MM[:SS]]` format. Learn more	No
`penalty.out_of_time.fixed`, `penalty.out_of_time.minute`	Penalties for violating the time window for visiting the location: a fixed penalty for an instance of violation and a penalty for each minute of violation. We recommend setting the same value for `early` and `late` penalties. Learn more	No
`penalty.early.fixed`, `penalty.early.minute`	Penalties for early arrival at the location: a fixed penalty for an instance of violation and a penalty for each minute of violation. Learn more	No
`penalty.late.fixed`, `penalty.late.minute`	Penalties for late arrival at the location: a fixed penalty for an instance of violation and a penalty for each minute of violation. Learn more	No

Visit conditions

Parameter	Description	Required
`last_visit_date`	Date of the last visit to the location before the start of planning. Learn more	No
`visit_count`	Required number of visits to the location over the planning period. Learn more	Yes
`penalty.visit_count.fixed`, `penalty.visit_count.per_visit`	Penalty for violating the `visit_count` parameter: a fixed penalty if at least one visit to the location was skipped and a penalty for each skipped visit to the location. Learn more	No
`min_days_between_visits`, `max_days_between_visits`	Minimum and maximum number of days between visits. Learn more	No
`penalty.min_days_between_visits.fixed`, `penalty.min_days_between_visits.per_day`	Penalty for violating the `min_days_between_visits` parameter: a fixed penalty if not enough time has passed between two visits and a penalty for each missing day between visits. Learn more	No
`penalty.max_days_between_visits.fixed`, `penalty.max_days_between_visits.per_day`	Penalty for violating the `max_days_between_visits` parameter: a fixed penalty if too much time has passed between two visits and a penalty for each extra day between visits. Learn more	No
`penalty.drop`	Fixed penalty if the location hasn't been visited once. Default value: 1,000,000. Learn more	No
`allowed_days`	List of days of the week on which you can visit the location. Learn more	No
`mandatory_days`	List of days of the week on which you must visit the location. Learn more	No
`denied_days`	List of days of the week on which you mustn't visit the location. Learn more	No
`preferred_days`	List of days of the week on which it's preferable to visit the location. Learn more	No
`penalty.preferred_days.fixed`, `penalty.preferred_days.per_day`	Penalty for visiting the location on any day other than those specified in `preferred_days`: a fixed penalty and a penalty for each day when the restriction is violated. Learn more	No
`max_distinct_visitors`	Maximum number of employees who can visit the location over the planning period. Learn more	No
`penalty.max_distinct_visitors.fixed`, `penalty.max_distinct_visitors.per_visitor`	Penalty for violating the `max_distinct_visitors` parameter: a fixed penalty if too many employees have visited the location and a penalty for each extra employee visiting the location. Learn more	No
`priority`	Location visit priority. Learn more	No

Cost

Parameter	Description	Required
`cost.additional_visitors.fixed`, `cost.additional_visitors.per_visitor`	Fixed cost if more than one employee has visited the location and cost for each additional employee visiting the location. Learn more	No

Tags and location types

Parameter	Description	Required
`required_tags`	List of tags that an employee must have to handle this location. Learn more	No
`optional_tags.N.tag`, `optional_tags.N.value`	Array of tags that an employee doesn't necessarily need to have to handle this location, but having them affects the route cost. Learn more	No
`load_types`	List of characteristics that determine incompatibility of locations (it's impossible to visit them within one route). Learn more	No

Additional parameters

Parameter	Description	Required
`custom_value`	Additional numeric attribute of the location, such as employee's remuneration for visiting the location. It can be used to calculate the route cost.	No
`shared_with_company_ids`	IDs of companies with access to information about planned visits to the location.	No
`use_in_proximity`	Flag indicating that the location is taken into account when planning high-density routes. Possible values: `true`/`false`. Default value: `true`.	No

Visits

Visit types are set on the visits sheet in Excel or in the locations.visits array in the API request.

Parameter	Description	Required
`id`	When planning via Excel, you need to specify the ID of the location (`location.id`) to be visited. This ID must match the `id` parameter on the `locations` sheet. There may be multiple rows with the same `id` value. When planning routes via the API, specify the unique ID of the type of visit:	Yes for Excel, no for the API
`title`	Visit name (type). Learn more	No
`service_duration_s`	Handling time for visits of this type. Learn more	Yes
`drop`	Penalty for skipping a visit of this type. Learn more	No
`allowed_days`	Days on which visits of this type are allowed. Learn more	No
`preffered_days`	Days on which visits of this type are preferred. Learn more	No
`denied_days`	Days on which visits of this type are prohibited. Learn more	No

Employees and vehicles

Parameters that specify the working conditions of employees and vehicle characteristics are set on the employees sheet in Excel or in the employees object in the API request.

Basic parameters

Parameter	Description	Required
`id`	Employee or vehicle ID. All such IDs within a task must be unique and have the same type: integer or string. Learn more	Yes
`ref`	Additional number of an employee or vehicle. Learn more	No
`imei`	Employee's GPS tracker number. Learn more	No
`phone`	Employee's phone number. Learn more	No
`routing_mode`	Transportation method. This parameter has a higher priority than `options.routing_mode`. Learn more	No
`travel_time_multiplier`	Travel time adjustment factor for fast or slow transportation methods. Default value: 1.	No
`service_duration_multiplier`	Coefficient for the adjustment of handling time for more or less qualified employees. Default value: 1. Learn more	No

Tags, geofences, and incompatibility of locations for employees

Parameter	Description	Required
`tags`	List of tags set for the employee or vehicle that are compatible with the tags set for the location (regular expressions of the extended POSIX standard are used). Learn more	No
`excluded_tags`	List of tags set for the employee or vehicle that are incompatible with the tags of the location (regular expressions of the extended POSIX standard are used). Learn more	No
`allowed_zones`, `forbidden_zones`	List of geofences where the employee can or can't visit locations. Learn more	No
`optional_zones.N.zone`, `optional_zones.N.value`	Array of geofences where visiting results in a penalty or bonus. Learn more	No
`incompatible_zones.N`	Array where each element determines a list of geofences that the employee mustn't visit within one route. Learn more	No
`incompatible_load_types.N`	Array where each element determines a set of incompatible location characteristics for the employee. Incompatible locations can't be visited within one route. Learn more	No

Route planning parameters

Parameter	Description	Required
`start_at`, `finish_at`	ID of the location where the employee will start their first route per day; finish their last route per day. Learn more	No
`max_runs`	Maximum number of employee routes per day. Default value: 1. Learn more	No
`max_edge_distance_m`, `max_edge_duration_s`	Maximum distance (in meters) between neighboring locations in a route; maximum travel duration (in seconds) between neighboring locations in a route. Learn more	No
`distance_between_days_starts_factor`, `distance_between_days_ends_factor`	Factor that applies when the cost of mileage between start/end route locations on neighboring days is added to the route cost. Default value: 0. Learn more	No
`duration_between_days_starts_factor`, `duration_between_days_ends_factor`	Factor that applies when the cost of travel duration between start/end route locations on neighboring days is added to the route cost. Default value: 0. Learn more	No
`first_edges_penalty_factor`, `last_edges_penalty_factor`	Factor that applies when the cost of the first segment of each route is added to the route cost. Default value: 0. Learn more	No
`global_proximity_attraction_point`	ID of the location whose proximity determines `global_proximity penalty`.	No
`global_proximity_factor`, `daily_proximity_factor`	Employee's route density. Learn more	No
`can_add_walking_edges`	Flag indicating on-foot sections on public transport routes. Learn more	No
`public_transport_cost.km`, `public_transport_cost.hour`, `public_transport_cost.edge`, `public_transport_cost.run`	Cost of using public transport. Learn more	No

Cost of work

Parameter	Description	Required
`cost.fixed`	Fixed cost of starting a route. By default, 3000 units. Learn more	No
`cost.km`	Cost of employee's work (or vehicle use) per kilometer. By default, 8 units. Learn more	No
`cost.hour`	Cost of employee's work (or vehicle use) per hour. By default, 100 units. Learn more	No
`cost.location`	Cost of visiting one location. The default is 0. Learn more	No
`cost.run`	Cost of completing one route. The default is 0. Learn more	No
`cost.route`	Cost of completing all routes. The default is 0. Learn more	No
`cost.waiting_hour`	Cost of one hour of wait time between visits. The default is 0. Learn more	No

Payouts to employees

Parameter	Description	Required
`payout.fixed`	Fixed payout for starting a route. By default, 3000 units. Learn more	No
`payout.km`	Payout to the employee per kilometer traveled. By default, 8 units. Learn more	No
`payout.hour`	Payout to the employee per hour. By default, 100 units. Learn more	No
`payout.location`	Payout for visiting one location. The default is 0. Learn more	No
`payout.run`	Payout for completing one route. The default is 0. Learn more	No
`payout.route`	Payout for completing all routes. The default is 0. Learn more	No
`payout.waiting_hour`	Payout for one hour of wait time between visits. The default is 0. Learn more	No

Leave

Parameter	Description	Required
`vacations`	Learn more	No

Employees' work schedule

Parameters that specify the employees' work schedule are set on the working_days sheet in Excel or in the employees.working_days array in the API request. Each row on the Excel sheet or each array element corresponds to a work schedule for one working day type (regular, shortened, pre-holiday, and so on).

Parameter	Description	Required
`id`	When planning routes via Excel, specify the ID of the employee (`employee.id`) the work schedule applies to. The ID must match the `id` parameter on the `employees` sheet. When planning routes from the API, specify the unique work schedule ID.	Yes for Excel, no for the API
`working_days`	List of employee's working days. Learn more	Yes
`start_time`	Start of the working day. Learn more	Yes
`max_finish_time`	End of the working day. Learn more	No
`hard_max_finish_time`	Maximum allowable time for the end of a working day. Learn more	No
`max_duration_s`, `hard_max_duration_s`	Maximum duration of a working day in seconds; hard limit on the maximum duration of a working day in seconds. Learn more	No
`max_mileage_km`	Maximum distance (mileage) covered by the employee during the working day, in kilometers.	No
`cost`	Cost of employee's work. Learn more	No
`maximal_stops`	Maximum number of stops per day. Learn more	No
`penalty.out_of_time.fixed`, `penalty.out_of_time.minute`, `penalty.late.fixed`, `penalty.late.minute`	Fixed penalties for an instance and for every minute of a time window violation, as well as for ending the work day late. Learn more	No
`penalty.stop_excess.fixed`, `penalty.stop_excess.per_stop`	Fixed penalties for an instance of violation and for each extra stop made during the day. Learn more	No
`penalty.max_mileage`	Penalty for exceeding the maximum mileage during the day.	No

Global options

Global options determine route planning parameters. They are set on the options sheet in Excel or in the options object in the API request.

Location and employee parameters have priority over similar global parameters.

Parameters

Parameter	Description	Required
`date`	Start date of the planning period. Learn more	Yes
`planning_days`	Number of days within the planning period. Learn more	Yes
`time_zone`	Planning time zone. Learn more	Yes
`allow_multiple_visitors`	Possibility of visiting the same location by different employees on different days. Possible values: `true`/`false`. Default value: `false`. Learn more	No
`avoid_tolls`	Avoid toll roads if possible (only for `driving` mode). Possible values: `true`/`false`. Default value: `false`.	No
`critical_lateness_risk_probability`	If the probability of late arrival at a location is greater than or equal to the specified value, the location is factored in in the `lateness_risk_locations_count` parameter. The probability is set as a percentage. Accepts a value from 1 to 50. Default value: 20.	No
`duration_between_days_starts_factor`, `distance_between_days_starts_factor`	Time and distance between starting points of the routes on neighboring days. Learn more	No
`duration_between_days_ends_factor`, `distance_between_days_ends_factor`	Time and distance between end points of the routes on neighboring days. Learn more	No
`fixed`	All routes specified in `initial_routes` are used without changes, and new employees and routes aren't added. Possible values: `true`/`false`. Default value: `false`.	No
`ignore_zones`	Ignore geofence-related options for locations and employees. Possible values: `true`/`false`. Default value: `false`.	No
`incompatible_load_types.N`	Array where each element determines a set of incompatible location characteristics. Incompatible locations can't be visited within one route. Learn more	No
`incompatible_zones`	Array where each element determines a list of geofences that an employee mustn't visit within one run.	No
`late_days_cost_increment`	Factor for planning visits to priority locations on earlier days. Learn more	No
`matrix_router`	Matrix router used for route planning. Possible values: `main` (default), recommended for Russia, CIS countries, and Türkiye; `global`, recommended for other countries; `geodesic`, distances are calculated directly without traffic jams; `auto`, automatic router selection based on the location position.	No
`minimize`	Route minimization criterion. Possible values: `cost` (default), `time`, `distance`, or `combined`.	No
`minimize_lateness_risk`	Minimize the probability of delays by avoiding routes where the estimated time of arrival is close to the end of the time window. Possible values: `true`/`false`. Default value: `false`.	No
`penalize_late_service`	Flag for penalizing late arrivals or late handling end time. Possible values: `true`/`false`. Default value: `false`. Learn more	No
`post_optimization`	Use of post-optimization. Possible values: `true`/`false`. Default value: `false`. Learn more	No
`global_proximity_factor`, `daily_proximity_factor`	Route density. Learn more	No
`routing_mode`	Default transportation method for employees. Default value: `driving`.	No
`solver_time_limit_s`	Maximum time to solve a planning task, in seconds. Learn more	No
`working_days_in_week`	Number of working days per week. It can't be used together with `working_days`. Learn more	No
`working_days`, `non_working_days`	Number of working and non-working days in a week. `working_days` can't be used together with `working_days_in_week`. Learn more	No
`penalty.multiorders.per_extra_point`, `penalty.multiorders.per_extra_employee`, `penalty.multiorders.per_extra_visit`	Penalties for visiting addresses with multiple locations. Default value: `0`. Learn more	No

Geofences

Geofences used when planning routes are set in the zones object in the API request. Geofences aren't set in Excel.

The zones object isn't required in the API request. However, in case you do use it, you must specify both parameters in each array element.

Parameter	Description	Required
`id`	Unique geofence ID. Learn more	Yes*
`geometry`	Coordinates of the points that are vertices of a geofence. Learn more	Yes*

* The parameter is required only if you use the zones object.

Contact support

Was the article helpful?

Planning parameters

Location and visit parameters