Add task

Enqueue a calendar planning task for processing.

Request

POST

https://courier.yandex.ru/vrs/api/v1/calendar_planning/tasks

Query parameters

Name

Description

apikey*

Type: string

API key.

lang

Type: string

Response locale in RFC-3066 format.

Default: en_US

Body

application/json

{
    "employees": [
        {
            "allowed_zones": [
                "string"
            ],
            "between_days_max_edge_distance_m": 0,
            "between_days_max_edge_duration_s": 0,
            "can_add_walking_edges": false,
            "cost": {
                "empty": 0,
                "empty_run": 0,
                "fixed": 3000,
                "hour": 300,
                "km": 50,
                "location": 0,
                "run": 0,
                "waiting_hour": 0
            },
            "daily_proximity_factor": 0,
            "distance_between_days_ends_factor": 0,
            "distance_between_days_starts_factor": 0,
            "duration_between_days_ends_factor": 0,
            "duration_between_days_starts_factor": 0,
            "excluded_tags": [
                "string"
            ],
            "finish_at": 0,
            "first_edges_penalty_factor": 0,
            "forbidden_zones": [
                "string"
            ],
            "global_proximity_attraction_point": 0,
            "global_proximity_factor": 0,
            "id": 0,
            "imei": 0,
            "incompatible_load_types": [
                [
                    "string"
                ]
            ],
            "incompatible_zones": [
                [
                    "string"
                ]
            ],
            "last_edges_penalty_factor": 0,
            "max_edge_distance_m": 0,
            "max_edge_duration_s": 0,
            "max_public_transport_edge_duration_s": 0,
            "max_runs": 1,
            "optional_zones": [
                {
                    "value": 0,
                    "zone": "string"
                }
            ],
            "payout": "string",
            "phone": "string",
            "ref": "string",
            "routing_mode": "driving",
            "service_duration_multiplier": 1,
            "start_at": 0,
            "tags": [
                "string"
            ],
            "travel_time_multiplier": 1,
            "use_walking_proximity": false,
            "vacations": [
                0,
                "string"
            ],
            "working_days": [
                {
                    "cost": 0,
                    "day": [
                        0,
                        "string"
                    ],
                    "fixed": false,
                    "hard_max_duration_s": 2592000,
                    "hard_max_finish_time": "string",
                    "hard_window": false,
                    "id": "string",
                    "max_duration_s": 172800,
                    "max_finish_time": "string",
                    "max_mileage_km": 0,
                    "maximal_stops": 0,
                    "min_duration_s": 0,
                    "minimal_stops": 0,
                    "start_time": "string",
                    "penalty": {
                        "stop_lack": {
                            "fixed": 0,
                            "per_stop": 0
                        },
                        "stop_excess": {
                            "fixed": 0,
                            "per_stop": 10000
                        },
                        "out_of_time": {
                            "fixed": 1000,
                            "minute": 17
                        },
                        "max_mileage": {
                            "fixed": 1000,
                            "km": 100
                        },
                        "late": {
                            "fixed": 1000,
                            "minute": 17
                        },
                        "early": {
                            "fixed": 1000,
                            "minute": 17
                        }
                    }
                }
            ],
            "public_transport_cost": {
                "edge": 0,
                "hour": 0,
                "km": 0,
                "run": 0
            },
            "penalty": {},
            "capacity": {
                "units": 0
            }
        }
    ],
    "initial_dropped_locations": [
        {
            "address": "string",
            "allowed_days": [
                0,
                "string"
            ],
            "comments": "string",
            "custom_value": 0,
            "denied_days": [
                0,
                "string"
            ],
            "description": "string",
            "drop_reason": "string",
            "fixed_drop": false,
            "hard_time_window": "string",
            "hard_window": false,
            "id": 0,
            "last_visit_date": "string",
            "load_types": [
                "string"
            ],
            "mandatory_days": [
                0,
                "string"
            ],
            "max_days_between_visits": 0,
            "max_distinct_visitors": 1,
            "max_total_employees": 0,
            "min_days_between_visits": 1,
            "optional_tags": [
                {
                    "tag": "string",
                    "value": 0
                }
            ],
            "phone": "string",
            "point": {
                "lat": 0,
                "lon": 0
            },
            "preferred_days": [
                0,
                "string"
            ],
            "priority": 0,
            "ref": "string",
            "required_tags": [
                "string"
            ],
            "service_duration_s": 0,
            "shared_with_company_ids": [
                0
            ],
            "time_window": "string",
            "time_windows": [
                {
                    "hard_time_window": "string",
                    "time_window": "string"
                }
            ],
            "title": "string",
            "type": "check-in",
            "use_in_proximity": true,
            "visit_count": 1,
            "visit_index": 0,
            "visits": [
                {
                    "allowed_days": [
                        0,
                        "string"
                    ],
                    "denied_days": [
                        0,
                        "string"
                    ],
                    "drop": 0,
                    "preferred_days": [
                        0,
                        "string"
                    ],
                    "service_duration_s": 0,
                    "title": "string"
                }
            ],
            "visit": {
                "allowed_days": [
                    0,
                    "string"
                ],
                "denied_days": [
                    0,
                    "string"
                ],
                "drop": 0,
                "preferred_days": [
                    0,
                    "string"
                ],
                "service_duration_s": 0,
                "title": "string"
            },
            "shipment_size": {
                "units": 0
            },
            "penalty": {
                "drop": 1000000,
                "visit_count": {
                    "fixed": 1000000,
                    "per_visit": 1000000
                },
                "preferred_days": {
                    "fixed": 0,
                    "per_day": 0
                },
                "out_of_time": {
                    "fixed": 1000,
                    "minute": 17
                },
                "min_days_between_visits": {
                    "fixed": 0,
                    "per_day": 10000
                },
                "max_distinct_visitors": {
                    "fixed": 0,
                    "per_visitor": 0
                },
                "max_days_between_visits": {
                    "fixed": 0,
                    "per_day": 10000
                },
                "late": {
                    "fixed": 1000,
                    "minute": 17
                },
                "early": {
                    "fixed": 1000,
                    "minute": 17
                }
            },
            "cost": {
                "additional_visitors": {
                    "fixed": 0,
                    "per_visitor": 0
                }
            }
        }
    ],
    "initial_routes": [
        {
            "actual_metrics": {
                "accomplished_visits": 0,
                "affecting_utilization": 0,
                "daily_proximity": 0,
                "early_location_count": 0,
                "failed_time_window_location_count": 0,
                "general_utilization": 0,
                "late_location_count": 0,
                "overtime_duration_penalty": 0,
                "overtime_duration_s": 0,
                "overtime_penalty": 0,
                "overtime_runs_count": 0,
                "overtime_runs_count_penalty": 0,
                "regular_time_runs_count": 0,
                "regular_time_runs_duration_s": 0,
                "route_custom_cost": 0,
                "route_payout": 0,
                "run_custom_cost": 0,
                "run_payout": 0,
                "total_cost": 0,
                "total_cost_with_penalty": 0,
                "total_custom_cost": 0,
                "total_daily_proximity_distance_m": 0,
                "total_daily_proximity_duration_s": 0,
                "total_daily_proximity_penalty": 0,
                "total_duration_cost": 0,
                "total_duration_s": 0,
                "total_early_count": 0,
                "total_early_duration_s": 0,
                "total_early_penalty": 0,
                "total_employee_locations_cost": 0,
                "total_failed_time_window_count": 0,
                "total_failed_time_window_duration_s": 0,
                "total_failed_time_window_penalty": 0,
                "total_fixed_cost": 0,
                "total_guaranteed_penalty": 0,
                "total_late_count": 0,
                "total_late_duration_s": 0,
                "total_late_penalty": 0,
                "total_mileage_penalty": 0,
                "total_multiorders_penalty": 0,
                "total_optional_tags_cost": 0,
                "total_optional_zones_cost": 0,
                "total_payout": 0,
                "total_penalty": 0,
                "total_public_transport_distance_cost": 0,
                "total_public_transport_distance_m": 0,
                "total_public_transport_duration_cost": 0,
                "total_public_transport_duration_s": 0,
                "total_public_transport_edges_cost": 0,
                "total_public_transport_runs_cost": 0,
                "total_runs_cost": 0,
                "total_service_duration_s": 0,
                "total_stop_count_penalty": 0,
                "total_transit_distance_cost": 0,
                "total_transit_distance_m": 0,
                "total_transit_duration_s": 0,
                "total_unfeasibility_penalty": 0,
                "total_units": 0,
                "total_waiting_duration_s": 0,
                "undertime_duration_penalty": 0,
                "undertime_duration_s": 0,
                "undertime_penalty": 0,
                "undertime_runs_count": 0,
                "undertime_runs_count_penalty": 0
            },
            "day": 0,
            "employee_id": 0,
            "fixed": false,
            "route": [
                {
                    "actual_arrival_time_s": 0,
                    "actual_departure_time_s": 0,
                    "actual_service_start_time_s": 0,
                    "arrival_time_s": 0,
                    "departure_time_s": 0,
                    "multi_order": false,
                    "node": {
                        "type": "location",
                        "value": {
                            "fixed_day": false,
                            "fixed_employee": false,
                            "id": 0,
                            "type": "check-in",
                            "undroppable": false
                        }
                    },
                    "waiting_duration_s": 0
                }
            ]
        }
    ],
    "locations": [
        {
            "address": "string",
            "allowed_days": [
                0,
                "string"
            ],
            "comments": "string",
            "custom_value": 0,
            "denied_days": [
                0,
                "string"
            ],
            "description": "string",
            "hard_time_window": "string",
            "hard_window": false,
            "id": 0,
            "last_visit_date": "string",
            "load_types": [
                "string"
            ],
            "mandatory_days": [
                0,
                "string"
            ],
            "max_days_between_visits": 0,
            "max_distinct_visitors": 1,
            "max_total_employees": 0,
            "min_days_between_visits": 1,
            "optional_tags": [
                {
                    "tag": "string",
                    "value": 0
                }
            ],
            "phone": "string",
            "point": {
                "lat": 0,
                "lon": 0
            },
            "preferred_days": [
                0,
                "string"
            ],
            "priority": 0,
            "ref": "string",
            "required_tags": [
                "string"
            ],
            "service_duration_s": 0,
            "shared_with_company_ids": [
                0
            ],
            "time_window": "string",
            "time_windows": [
                {
                    "hard_time_window": "string",
                    "time_window": "string"
                }
            ],
            "title": "string",
            "type": "check-in",
            "use_in_proximity": true,
            "visit_count": 1,
            "visits": [
                {
                    "allowed_days": [
                        0,
                        "string"
                    ],
                    "denied_days": [
                        0,
                        "string"
                    ],
                    "drop": 0,
                    "preferred_days": [
                        0,
                        "string"
                    ],
                    "service_duration_s": 0,
                    "title": "string"
                }
            ],
            "shipment_size": {
                "units": 0
            },
            "penalty": {
                "drop": 1000000,
                "visit_count": {
                    "fixed": 1000000,
                    "per_visit": 1000000
                },
                "preferred_days": {
                    "fixed": 0,
                    "per_day": 0
                },
                "out_of_time": {
                    "fixed": 1000,
                    "minute": 17
                },
                "min_days_between_visits": {
                    "fixed": 0,
                    "per_day": 10000
                },
                "max_distinct_visitors": {
                    "fixed": 0,
                    "per_visitor": 0
                },
                "max_days_between_visits": {
                    "fixed": 0,
                    "per_day": 10000
                },
                "late": {
                    "fixed": 1000,
                    "minute": 17
                },
                "early": {
                    "fixed": 1000,
                    "minute": 17
                }
            },
            "cost": {
                "additional_visitors": {
                    "fixed": 0,
                    "per_visitor": 0
                }
            }
        }
    ],
    "options": {
        "allow_multiple_visitors": false,
        "avoid_tolls": false,
        "avoid_zones": [
            "string"
        ],
        "critical_lateness_risk_probability": 20,
        "daily_proximity_factor": 0,
        "date": "string",
        "distance_between_days_ends_factor": 0,
        "distance_between_days_starts_factor": 0,
        "duration_between_days_ends_factor": 0,
        "duration_between_days_starts_factor": 0,
        "fixed": false,
        "fixed_drops": false,
        "global_proximity_factor": 0,
        "incompatible_load_types": [
            [
                "string"
            ]
        ],
        "incompatible_zones": [
            [
                "string"
            ]
        ],
        "late_days_cost_increment": 0,
        "minimize_lateness_risk": false,
        "non_working_days": [
            0,
            "string"
        ],
        "penalize_late_service": true,
        "planning_days": 0,
        "post_optimization": false,
        "quality": "low",
        "restart_on_drop": false,
        "routing_mode": "driving",
        "time_zone": 0,
        "working_days": [
            0,
            "string"
        ],
        "working_days_in_week": 5,
        "penalty": {
            "multiorders": {
                "per_extra_employee": 0,
                "per_extra_point": 0,
                "per_extra_visit": 0
            }
        }
    },
    "zones": [
        {
            "id": "string",
            "geometry": {
                "coordinates": [
                    [
                        [
                            0
                        ]
                    ]
                ],
                "type": "string"
            }
        }
    ]
}

Name	Description
locations*	Type: locations[] List of locations. Location of order to deliver from depot. Min items: `1`
options*	Type: solver_options_mvrp_1 Solver options. It is forbidden to specify options that are not present in the list below.
employees	Type: employee[] List of employees, available for route planning. Employees specification. Min items: `1`
initial_dropped_locations	Type: initial_dropped_locations[] List of dropped visits Location of order to deliver from depot.
initial_routes	Type: initial_routes[] List of routes in old response, which has to be loaded into solver. More information
zones	Type: zones[]

locations

Location of order to deliver from depot.

Name	Description
id*	Type: integer or string Location ID. All locations IDs in task must be unique and have the same type: integer or string. More information
point*	Type: coordinate_1 WGS84 coordinate of a location. More information
address	Type: string Address of the location. More information
allowed_days	Type: (integer or string)[] The list of days allowed to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
comments	Type: string Comments. More information
cost	Type: locations_cost Location cost. More information
custom_value	Type: number A custom numeric value, associated with location (E.g. the reward for the employee for visiting this location). May be used as a component in employee cost function. More information
denied_days	Type: (integer or string)[] The list of days denied to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
description	Type: string Location description. More information
hard_time_window	Type: string Allowed hard time window to visit location, in `[D.]HH[:MM[:SS]] - [D.]HH[:MM[:SS]]` format. Hard time window must include time range defined in corresponding `time_window` field. Fields `hard_time_window` and `hard_window` are mutually exclusive. More information
hard_window	Type: boolean Restricts time window relaxation during route planning. If location cannot be visited within a specified time window, it will be excluded from the route and added to `dropped_locations` field in the response. This field is useful to model orders that cannot be completed within the time window, (e.g. due to conflicts with other orders). More information Default: `false`
last_visit_date	Type: string The date of the last location visit before the start of planning period. More information
load_types	Type: string[] Defines compatibility with other locations in the route. mustn`t be defined only for` base` location type. More information Type of load. More information
mandatory_days	Type: (integer or string)[] The list of days mandatory to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
max_days_between_visits	Type: integer Maximal interval (in days) between two location visits. More information Min value: `1`
max_distinct_visitors	Type: integer Maximal number of different employees visiting location. More information Default: `1` Min value: `1`
max_total_employees	Type: integer Maximal number of employees that can be served by an anchor location. Unlimited by default.
min_days_between_visits	Type: integer Minimal interval (in days) between two location visits. More information Default: `1` Min value: `1`
optional_tags	Type: locations_optional_tags_item[] A list of tags that an employee does not need to have to visit the location. These tags can reduce or increase the route cost. More information An optional tag for the location.
penalty	Type: locations_penalty Penalties for missing visits and violating location visit windows. More information
phone	Type: string Phone number of check-in receiver. More information
preferred_days	Type: (integer or string)[] The list of days preferred to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
priority	Type: integer Location visit priority, the lower is this value, the higher is priority. Locations with higher `priority` value can only be visited by the same worker on later day, than this location. Additionally, locations with higher `priority` value can only be visited in the solution if all visits of all locations with this `priority` value are accomplished. More information
ref	Type: string Additional location ref. More information
required_tags	Type: string[] List of tags a employee must have to arrive at the location. More information An arbitrary tag.
service_duration_s	Type: number The locations handling time. Handling time may include any operations at the location, such as loading or unloading or any other time/activity associated with the location (except waiting time, which is calculated as the difference between the employees arrival at the location and the start of handling time). More information Default: `0` Min value: `0` Max value: `3153600000`
shared_with_company_ids	Type: integer[] IDs of the companies that can access the order information.More information Min value: `0`
shipment_size	Type: locations_shipment_size Shipment size (dimensions and/or weight).
time_window	Type: string Allowed time window to visit location, in `[D.]HH[:MM[:SS]] - [D.]HH[:MM[:SS]]` format.More information
time_windows	Type: locations_time_windows_item[] List of allowed time windows. Time windows can not overlap. Fields `time_window` and `time_windows` are mutually exclusive. Either none or all of `time_window` must have corresponding `hard_time_window`. More information
title	Type: string Location title. More information
type	Type: string Defines the type of location: `check-in` or `base`. `check-in`: Location to be visited. `base`: A service location that an employee can specify as the start or end point of their route using the `start_at` and `finish_at` properties. More information Default: `check-in` Enum: `check-in`, `base`
use_in_proximity	Type: boolean When `false`, this location will be ignored in computation of daily and global proximity. More information Default: `true`
visit_count	Type: integer Required number of visits for a location in planning period. More information Default: `1` Min value: `1`
visits	Type: locations_visits_item[] Descriptions of individual location visits.More information The properties of a specific type of location visits.

solver_options_mvrp_1

Solver options. It is forbidden to specify options that are not present in the list below.

Name	Description
date*	Type: string Starting date for all routes (`YYYY-MM-DD` format), defaults to current date. More information Pattern: `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
planning_days*	Type: integer Planning period in days. More information Min value: `1`
time_zone*	Type: number or string
allow_multiple_visitors	Type: boolean Allow one location to be visited by different employees. More information Default: `false`
avoid_tolls	Type: boolean Do not use toll roads if possible (only for `driving`routing mode). More information Default: `false`
avoid_zones	Type: string[] List of zones that cannot be entered when performing a route. These zones will be avoided even if the fastest route passes through them. The total number of corners in zone polygons must not exceed 300. Zone id. Min items: `0` Max items: `100`
critical_lateness_risk_probability	Type: number If a probability of being late on a location is greater or equal than a specified value, than the location is accounted in `lateness_risk_location_count`. The probability is defined in percent.More information Default: `20` Min value: `1` Max value: `50`
daily_proximity_factor	Type: number Level of location proximity influence on employee routes during the day. Recommended values are from `0.0` to `1.0`. Using this option makes locations closer to the last location in run on every day. More information Default: `0` Min value: `0` Max value: `10`
distance_between_days_ends_factor	Type: number Coefficient with which the cost for transit distances between run ending locations on consecutive days is added to the route costMore information Default: `0` Min value: `0`
distance_between_days_starts_factor	Type: number Coefficient with which the cost for transit distances between run starting locations on consecutive days is added to the route costMore information Default: `0` Min value: `0`
duration_between_days_ends_factor	Type: number Coefficient with which the cost for transit durations between run ending locations on consecutive days is added to the route costMore information Default: `0` Min value: `0`
duration_between_days_starts_factor	Type: number Coefficient with which the cost for transit durations between run starting locations on consecutive days is added to the route costMore information Default: `0` Min value: `0`
fixed	Type: boolean All routes, specified in `initial_routes`, are used without changes, new runs can not be added.More information Default: `false`
fixed_drops	Type: boolean All visits, specified in `initial_dropped_locations`, will be dropped. Default: `false`
global_proximity_factor	Type: number Level of location proximity influence on employee routes during the planning period. Recommended values are from `0.0` to `1.0`. Using this option makes locations closer to the last location in route. Using both `proximity_factor` and `global_proximity_factor` makes routes more tolerant to moving locations to the end of route. Note, that using proximity will decrease optimality of computed routes in terms of costs and penalties. More information Default: `0` Min value: `0` Max value: `10`
incompatible_load_types	Type: string[][] Each item in this array defines list of location load types, that should not be handled within the same employee run. More information List of load types. More information Type of load. More information
incompatible_zones	Type: string[][] Each item in this array defines list of location zones, that should not be visited within the same employee run. More information List of zones which location belongs to. More information Zone id.
late_days_cost_increment	Type: number Parameter, helping solver to visit locations on earlier days. When this parameter is used, during optimization the cost of every used working day is increased by parameter value, multiplied by the day index (where day indices start with 0) ands coefficient declining from 1 to 0 during optimization (i.e. this parameter does not affect the final solutuion cost). More information Default: `0`
minimize_lateness_risk	Type: boolean Compute and minimize the probability of being late to locations. In other words, avoid routes such that the estimated time of arrival is close to the end of a time window. More information Default: `false`
non_working_days	Type: (integer or string)[] The list of non-working days during the planning period. Has a higher priority than the working_days and working_days_in_week.Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
penalize_late_service	Type: boolean The option determines whether the employee should be penalized for the late start or end of a location visit. When `false`, `late` penalty is applied if a employee arrived to the location/depot or started serving the depot after the end of the time window. Note that for multi-orders the service start time of the whole multi-order is used for each suborder rather than the suborder's own service start. When `true`, `late` penalty is applied if the location, depot or shift service was finished after the end of the time window. In most cases turning this option on is equivalent to decreasing the ends of all the time windows by `service_duration_s` of the corresponding locations, depots and shifts. However, it provides its own mechanics for the cases when it is not clear how much time will pass since arrival to the location till the end of service, e.g. in the cases of serving multi-orders. It is recommended to set this to true if it is important to serve multi-orders in time rather than to arrive at a multi-order location in time. More information Default: `true`
penalty	Type: solver_options_mvrp_1_penalty Penalties for global solution limitations violation.
post_optimization	Type: boolean Use post optimization: restart algorithm in the last 10% operations with disabled `global_proximity` and balancing. More information Default: `false`
quality	Type: string Route optimization quality: `low` — debug mode for development and validation of constraints, shortest run time; `normal` — baseline optimization quality, average run time; `high` — highest possible quality, longest run time. Required field.More information Default: `normal` Enum: `low`, `normal`, `high`
restart_on_drop	Type: boolean Restart to optimize only non-dropped orders, in case we haven't find solutions without drops. Enable this option if drops are expected and acceptable for your business scenario. Default: `false`
routing_mode	Type: string Mode of routing. More information `driving` — default mode, routing with car profile; `truck` — routing with truck profile; `walking` — routing with pedestrian profile, only on roads allowed for pedestrian traffic; `transit` — routing with pedestrian profile combined with public transport; `bicycle` - routing with bicycle profile. More information Default: `driving` Enum: `driving`, `truck`, `walking`, `transit`, `bicycle`
working_days	Type: (integer or string)[] The list of working days during the planning period. Incompatible with the working_days_in_week option. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
working_days_in_week	Type: integer Number of working days in week. Working days always start from Monday and distributed in the week evenly. Incompatible with the working_days option. More information Default: `5` Min value: `1` Max value: `7`

employee

Employees specification.

Name	Description
id*	Type: integer or string Employees ID. All employee IDs in task must be unique and have the same type: integer or string. More information
allowed_zones	Type: string[] List of zones, which can be visited by employee. More information Zone id.
between_days_max_edge_distance_m	Type: number Maximal transit distance (in meters) between the first/last locations of neighboring days. More information Min value: `0`
between_days_max_edge_duration_s	Type: number Maximal transit duration (in seconds) between the first/last locations of neighboring days. More information Min value: `0`
can_add_walking_edges	Type: boolean Employee with `routing_mode` = `transit` can go between close locations by walking.More information Default: `false`
capacity	Type: employee_capacity Employee capacity
cost	Type: employee_cost_0 or string or employee_cost_1
daily_proximity_factor	Type: number Level of location proximity influence on employee routes during the day. Recommended values are from `0.0` to `1.0`. Using this option makes locations closer to the last location in run on every day. More information Default: `0` Min value: `0` Max value: `10`
distance_between_days_ends_factor	Type: number Coefficient with which the cost for transit distances between run ending locations on consecutive days is added to the route cost.More information Default: `0` Min value: `0`
distance_between_days_starts_factor	Type: number Coefficient with which the cost for transit distances between run starting locations on consecutive days is added to the route costMore information Default: `0` Min value: `0`
duration_between_days_ends_factor	Type: number Coefficient with which the cost for transit durations between run ending locations on consecutive days is added to the route cost.More information Default: `0` Min value: `0`
duration_between_days_starts_factor	Type: number Coefficient with which the cost for transit durations between run starting locations on consecutive days is added to the route cost.More information Default: `0` Min value: `0`
excluded_tags	Type: string[] List of excluding employee tags, checked for compatibility with location tags (POSIX-extended regular expression are used). More information An arbitrary tag or POSIX-extended regular expression.
finish_at	Type: integer or string Defines `id` of a location with type `base` where the employee should finish the route.More information
first_edges_penalty_factor	Type: number A factor that determines extra penalty/bonus for the first edge of each run.More information Default: `0`
forbidden_zones	Type: string[] List of zones, which can not be visited by employee. More information Zone id.
global_proximity_attraction_point	Type: integer or string Defines `id` of a location with type `base`, the distance to which is calculated for the `global_proximity` penalty.More information
global_proximity_factor	Type: number Level of location proximity influence on employee routes during the planning period. Recommended values are from `0.0` to `1.0`. Using this option makes locations closer to the last location in route. Using both `proximity_factor` and `global_proximity_factor` makes routes more tolerant to moving locations to the end of route. Note, that using proximity will decrease optimality of computed routes in terms of costs and penalties. More information Default: `0` Min value: `0` Max value: `10`
imei	Type: integer The IMEI number of the GPS tracker. More information
incompatible_load_types	Type: string[][] Each item in this array defines list of location load types, that should not be handled within the same employee run (overrides `incompatible_load_types` value specified in `options`). More information List of load types. More information Type of load. More information
incompatible_zones	Type: string[][] Each item in this array defines list of location zones, that should not be visited within the same employee run. (overrides `incompatible_zones` value specified in `options`). More information List of zones which location belongs to. More information Zone id.
last_edges_penalty_factor	Type: number A factor that determines extra penalty/bonus for the last edge of each run.More information Default: `0`
max_edge_distance_m	Type: number Maximal transit distance (in meters) between two consequtive locations in employee route.More information Min value: `0`
max_edge_duration_s	Type: number Maximal transit duration (in seconds) between two consecutive locations in employee routeMore information Min value: `0`
max_public_transport_edge_duration_s	Type: number Maximal transit duration (in seconds) between two consecutive locations in employee route using public transport.More information Min value: `0`
max_runs	Type: integer Maximal number of the employee routes per day. More information Default: `1`
optional_zones	Type: employee_optional_zones_item[] Array of optional zones with bonus or penalty.More information An optional tag with bonus. More information
payout	Type: string or employee_payout_0
penalty	Type: object Penalties for employee limitations violation.
phone	Type: string Phone number of the employee. More information
public_transport_cost	Type: employee_public_transport_cost Cost for public transport use. More information
ref	Type: string Additional number of the employee. More information
routing_mode	Type: string Mode of routing. If present, overrides `routing_mode` specified in solver options. More information `driving` — default mode, routing with car profile; `truck` — routing with truck profile; `walking` — routing with pedestrian profile, only on roads allowed for pedestrian traffic; `transit` - routing with pedestrian profile combined with public transport; `bicycle` - routing wtih bicycle profile. Enum: `driving`, `truck`, `walking`, `transit`, `bicycle`
service_duration_multiplier	Type: number Coefficient for the adjustment of handling time for more or less qualified employees. More information Default: `1` Min value: `0.001`
start_at	Type: integer or string Defines `id` of a location with type `base` where the employee should start the route. More information
tags	Type: string[] List of employee tags, checked for compatibility with location tags (POSIX-extended regular expression are used). More information An arbitrary tag or POSIX-extended regular expression.
travel_time_multiplier	Type: number Coefficient for the adjustment of handling time for more or less qualified employees. More information Default: `1` Min value: `0.001`
use_walking_proximity	Type: boolean Use walking cost matrix when computing proximity penalty for the vehicles routes Default: `false`
vacations	Type: (integer or string)[] The list of vacation days during the planning period. Incompatible with the working_days_in_week option. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
working_days	Type: employee_working_days_item[] The list of working days parameters. More information Employees working day. More information

initial_dropped_locations

Location of order to deliver from depot.

Name	Description
drop_reason*	Type: string Explanation why the location was dropped.
id*	Type: integer or string Location ID. All locations IDs in task must be unique and have the same type: integer or string. More information
point*	Type: coordinate_1 WGS84 coordinate of a location. More information
visit_index*	Type: integer
address	Type: string Address of the location. More information
allowed_days	Type: (integer or string)[] The list of days allowed to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
comments	Type: string Comments. More information
cost	Type: initial_dropped_locations_cost Location cost. More information
custom_value	Type: number A custom numeric value, associated with location (E.g. the reward for the employee for visiting this location). May be used as a component in employee cost function. More information
denied_days	Type: (integer or string)[] The list of days denied to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
description	Type: string Location description. More information
fixed_drop	Type: boolean Default: `false`
hard_time_window	Type: string Allowed hard time window to visit location, in `[D.]HH[:MM[:SS]] - [D.]HH[:MM[:SS]]` format. Hard time window must include time range defined in corresponding `time_window` field. Fields `hard_time_window` and `hard_window` are mutually exclusive. More information
hard_window	Type: boolean Restricts time window relaxation during route planning. If location cannot be visited within a specified time window, it will be excluded from the route and added to `dropped_locations` field in the response. This field is useful to model orders that cannot be completed within the time window, (e.g. due to conflicts with other orders). More information Default: `false`
last_visit_date	Type: string The date of the last location visit before the start of planning period. More information
load_types	Type: string[] Defines compatibility with other locations in the route. mustn`t be defined only for` base` location type. More information Type of load. More information
mandatory_days	Type: (integer or string)[] The list of days mandatory to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
max_days_between_visits	Type: integer Maximal interval (in days) between two location visits. More information Min value: `1`
max_distinct_visitors	Type: integer Maximal number of different employees visiting location. More information Default: `1` Min value: `1`
max_total_employees	Type: integer Maximal number of employees that can be served by an anchor location. Unlimited by default.
min_days_between_visits	Type: integer Minimal interval (in days) between two location visits. More information Default: `1` Min value: `1`
optional_tags	Type: initial_dropped_locations_optional_tags_item[] A list of tags that an employee does not need to have to visit the location. These tags can reduce or increase the route cost. More information An optional tag for the location.
penalty	Type: initial_dropped_locations_penalty Penalties for missing visits and violating location visit windows. More information
phone	Type: string Phone number of check-in receiver. More information
preferred_days	Type: (integer or string)[] The list of days preferred to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
priority	Type: integer Location visit priority, the lower is this value, the higher is priority. Locations with higher `priority` value can only be visited by the same worker on later day, than this location. Additionally, locations with higher `priority` value can only be visited in the solution if all visits of all locations with this `priority` value are accomplished. More information
ref	Type: string Additional location ref. More information
required_tags	Type: string[] List of tags a employee must have to arrive at the location. More information An arbitrary tag.
service_duration_s	Type: number The locations handling time. Handling time may include any operations at the location, such as loading or unloading or any other time/activity associated with the location (except waiting time, which is calculated as the difference between the employees arrival at the location and the start of handling time). More information Default: `0` Min value: `0` Max value: `3153600000`
shared_with_company_ids	Type: integer[] IDs of the companies that can access the order information.More information Min value: `0`
shipment_size	Type: initial_dropped_locations_shipment_size Shipment size (dimensions and/or weight).
time_window	Type: string Allowed time window to visit location, in `[D.]HH[:MM[:SS]] - [D.]HH[:MM[:SS]]` format.More information
time_windows	Type: initial_dropped_locations_time_windows_item[] List of allowed time windows. Time windows can not overlap. Fields `time_window` and `time_windows` are mutually exclusive. Either none or all of `time_window` must have corresponding `hard_time_window`. More information
title	Type: string Location title. More information
type	Type: string Defines the type of location: `check-in` or `base`. `check-in`: Location to be visited. `base`: A service location that an employee can specify as the start or end point of their route using the `start_at` and `finish_at` properties. More information Default: `check-in` Enum: `check-in`, `base`
use_in_proximity	Type: boolean When `false`, this location will be ignored in computation of daily and global proximity. More information Default: `true`
visit	Type: initial_dropped_locations_visit The properties of a specific type of location visits.
visit_count	Type: integer Required number of visits for a location in planning period. More information Default: `1` Min value: `1`
visits	Type: initial_dropped_locations_visits_item[] Descriptions of individual location visits.More information The properties of a specific type of location visits.

initial_routes

Name	Description
day*	Type: integer A day when location should be visited. Min value: `0`
route*	Type: initial_routes_route_element[] Sequence of route nodes, comprising a route. Route node, contains information about a visited location or a work break, transit information and arrival time. More information
actual_metrics	Type: route_metrics Actual route metrics for fixed run.
employee_id	Type: integer or string Employees ID. All employee IDs in task must be unique and have the same type: integer or string. More information
fixed	Type: boolean A route, specified in `initial_routes`, is used without changes. More information Default: `false`

zones

Name

Description

geometry*

Type: zones_geometry

id*

Type: string

Zone number

coordinate_1

WGS84 coordinate of a location. More information

Name

Description

lat*

Type: number

Min value: -90

Max value: 90

lon*

Type: number

Min value: -180

Max value: 180

locations_cost

Location cost. More information

Name

Description

additional_visitors

Type: locations_cost_additional_visitors

Constituents of the locations service cost if it was visited by several employees. More information

locations_optional_tags_item

An optional tag for the location.

Name

Description

tag*

Type: string

An arbitrary tag.

value*

Type: number

Value of the tag. When location is served by a employee with a matching tag in tags field, this value is subtracted from the route cost. When the matching tag is in excluded_tags field, this value is added to the route cost.More information

locations_penalty

Penalties for missing visits and violating location visit windows. More information

Name	Description
drop	Type: number or penalty_drop_0
early	Type: locations_penalty_early Constituents of penalties for violation of handling time — early visit to a location (used instead of the `out_of_time` penalty).More information
late	Type: locations_penalty_late Penalty components for late visits (used instead of `out_of_time` penalty). Whether the start or the end of service during the visit is used to penalize for lateness is determined by the `penalize_late_service` option.More information
max_days_between_visits	Type: locations_penalty_max_days_between_visits Penalty components for the violation of days between visits requirement. More information
max_distinct_visitors	Type: locations_penalty_max_distinct_visitors Penalty components for having location visited by more distinct employees, than specified in `max_distinct_visitors` option. More information
min_days_between_visits	Type: locations_penalty_min_days_between_visits Penalty components for the violation of days between visits requirement. More information
out_of_time	Type: locations_penalty_out_of_time Penalty components for time window failure. Can be used to set the values of `early` and `late` options simultaneously, and each value is overridden if the respective option is also defined.More information
preferred_days	Type: locations_penalty_preferred_days Penalty components for failing to visit location on some of the week days, specified in `preferred_days` option. More information
visit_count	Type: locations_penalty_visit_count Constituents of penalties for missed visits to a location. More information

locations_shipment_size

Shipment size (dimensions and/or weight).

Name

Description

units

Type: integer

Size of shipment in custom units.

Default: 0

Min value: 0

Max value: 1000000000

locations_time_windows_item

Name

Description

time_window*

Type: string

Allowed time window to visit location, in [D.]HH[:MM[:SS]] - [D.]HH[:MM[:SS]] format.More information

hard_time_window

Type: string

Allowed hard time window to visit location, in [D.]HH[:MM[:SS]] - [D.]HH[:MM[:SS]] format. Hard time window must include time range defined in corresponding time_window field. Fields hard_time_window and hard_window are mutually exclusive. More information

locations_visits_item

The properties of a specific type of location visits.

Name	Description
allowed_days	Type: (integer or string)[] The list of days allowed to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
denied_days	Type: (integer or string)[] The list of days denied to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
drop	Type: number Penalty for missing to visit of this type. Overrides `location.penalty.drop` value. More information
preferred_days	Type: (integer or string)[] The list of days preferred to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
service_duration_s	Type: number Handling time at the location. Overrides `location.service_duration_s` value. More information
title	Type: string Visits title (type). More information

solver_options_mvrp_1_penalty

Penalties for global solution limitations violation.

Name

Description

multiorders

Type: solver_options_mvrp_1_penalty_multiorders

Penalty components for extra visits to addresses with several locations.More information

employee_capacity

Employee capacity

Name

Description

units

Type: integer

The maximum number of units that the employee can process in one working day. By default there are no restrictions.

Min value: 0

Max value: 1000000000

employee_cost_0

Employees cost. More information

Name	Description
empty	Type: number Cost per fact of unused employee. Cost occurred if employee is not included in route.More information Default: `0` Min value: `0`
empty_run	Type: number Cost per single employee unused run from depot to locations.More information Default: `0` Min value: `0`
fixed	Type: number Cost per fact of employee use. More information Default: `3000` Min value: `0`
hour	Type: number Cost of using employee per hour. It should not be zero or very small, otherwise you may get routes which are not optimal in terms of time.More information Default: `300` Min value: `0`
km	Type: number Cost of using employee per kilometer. It should not be zero or very small, otherwise you may get routes which are not optimal in terms of distance.More information Default: `50` Min value: `0`
location	Type: number Cost of visit per location (default 0). More information Default: `0` Min value: `0`
run	Type: number Cost per single employee run. More information Default: `0` Min value: `0`
waiting_hour	Type: number Cost of waiting per hour. If not defined, the value specified in the `hour` field is used.More information Min value: `0`

employee_cost_1

Description of the cost of using the employee with the possibility of specifying arithmetic expressions for individual parts of the route. The total cost will be obtained as the sum of all the specified expressions for all parts included in the route.

Name

Description

route

Type: string

Arithmetic expression representing route cost

run

Type: string

Arithmetic expression representing run cost

employee_optional_zones_item

An optional tag with bonus. More information

Name

Description

value*

Type: number

Value of the zone. This value is subtracted from the route cost for any served location with a matching zone.For location with multiple matching zones will be chosen the maximum bonus.More information

zone*

Type: string

Zone id.

employee_payout_0

Description of the payout to the employee for completing the route with the possibility of specifying arithmetic expressions for individual parts of the route. The total payout will be obtained as the sum of all the specified expressions for all parts included in the route.More information

Name

Description

route

Type: string

Arithmetic expression representing route cost

run

Type: string

Arithmetic expression representing run cost

employee_public_transport_cost

Cost for public transport use. More information

Name	Description
edge	Type: number Fixed cost for every transit between two consucutive locations, using public transport.More information Default: `0` Min value: `0`
hour	Type: number Cost of using public transport per hour. More information Default: `0` Min value: `0`
km	Type: number Cost of using public transport per kilometer (only pedestrian distance part of routes is actually considered).More information Default: `0` Min value: `0`
run	Type: number Fixed cost for every employee working day, when public transport is used. More information Default: `0` Min value: `0`

employee_working_days_item

Employees working day. More information

Name	Description
start_time*	Type: string or array
cost	Type: number Cost of the employee's work on this day. More information Default: `0`
day	Type: integer or string or array
fixed	Type: boolean All routes of the employee, specified in `initial_routes`, are used without changes, new routes can not be added.More information Default: `false`
hard_max_duration_s	Type: number Hard limit on the maximum shift duration in seconds. If both `max_duration_s` and `hard_max_duration_s` are present, the value of `hard_max_duration_s` should be greater or equal to the value of `max_duration_s`. More information Default: `2592000` Min value: `0` Max value: `3153600000`
hard_max_finish_time	Type: string Maximal a valid time for the end of the working day. More information
hard_window	Type: boolean Restricts time window relaxation during route planning. When `true`, employees are allowed to finish a shift only within the specified time window. More information Default: `false`
id	Type: string Unique identifier of a shift. More information
max_duration_s	Type: number Maximal duration of a shift in seconds. If a planned shift duration is greater than specified, the shift out of time penalties are applied. More information Default: `172800` Min value: `0` Max value: `3153600000`
max_finish_time	Type: string The latest possible time of the end of the working day. More information
max_mileage_km	Type: number Maximal mileage of the employee during the shift in kilometers. If a planned mileage is greater than this value, the penalties from a shift parameter `penalty.max_mileage` are applied. More information Min value: `0`
maximal_stops	Type: integer Maximal number of stops per day, if the final stop count is greater than this value, `stop_excess` penalties are applied.More information Default: `0` Min value: `0`
min_duration_s	Type: number Minimal duration of a shift in seconds. If a planned shift duration is greater than specified, the shift out of time penalties are applied. Default: `0` Min value: `0` Max value: `3153600000`
minimal_stops	Type: integer Minimal number of shift stops, if the final stop count is less than this value, `stop_lack` penalties are applied. More information Default: `0` Min value: `0`
penalty	Type: employee_working_days_penalty Penalties for shift constraints violation. More information

initial_dropped_locations_cost

Location cost. More information

Name

Description

additional_visitors

Type: initial_dropped_locations_cost_additional_visitors

Constituents of the locations service cost if it was visited by several employees. More information

initial_dropped_locations_optional_tags_item

An optional tag for the location.

Name

Description

tag*

Type: string

An arbitrary tag.

value*

Type: number

initial_dropped_locations_penalty

Penalties for missing visits and violating location visit windows. More information

Name	Description
drop	Type: number or penalty_drop_0_1
early	Type: initial_dropped_locations_penalty_early Constituents of penalties for violation of handling time — early visit to a location (used instead of the `out_of_time` penalty).More information
late	Type: initial_dropped_locations_penalty_late Penalty components for late visits (used instead of `out_of_time` penalty). Whether the start or the end of service during the visit is used to penalize for lateness is determined by the `penalize_late_service` option.More information
max_days_between_visits	Type: initial_dropped_locations_penalty_max_days_between_visits Penalty components for the violation of days between visits requirement. More information
max_distinct_visitors	Type: initial_dropped_locations_penalty_max_distinct_visitors Penalty components for having location visited by more distinct employees, than specified in `max_distinct_visitors` option. More information
min_days_between_visits	Type: initial_dropped_locations_penalty_min_days_between_visits Penalty components for the violation of days between visits requirement. More information
out_of_time	Type: initial_dropped_locations_penalty_out_of_time Penalty components for time window failure. Can be used to set the values of `early` and `late` options simultaneously, and each value is overridden if the respective option is also defined.More information
preferred_days	Type: initial_dropped_locations_penalty_preferred_days Penalty components for failing to visit location on some of the week days, specified in `preferred_days` option. More information
visit_count	Type: initial_dropped_locations_penalty_visit_count Constituents of penalties for missed visits to a location. More information

initial_dropped_locations_shipment_size

Shipment size (dimensions and/or weight).

Name

Description

units

Type: integer

Size of shipment in custom units.

Default: 0

Min value: 0

Max value: 1000000000

initial_dropped_locations_time_windows_item

Name

Description

time_window*

Type: string

Allowed time window to visit location, in [D.]HH[:MM[:SS]] - [D.]HH[:MM[:SS]] format.More information

hard_time_window

Type: string

initial_dropped_locations_visit

The properties of a specific type of location visits.

Name	Description
allowed_days	Type: (integer or string)[] The list of days allowed to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
denied_days	Type: (integer or string)[] The list of days denied to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
drop	Type: number Penalty for missing to visit of this type. Overrides `location.penalty.drop` value. More information
preferred_days	Type: (integer or string)[] The list of days preferred to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
service_duration_s	Type: number Handling time at the location. Overrides `location.service_duration_s` value. More information
title	Type: string Visits title (type). More information

initial_dropped_locations_visits_item

The properties of a specific type of location visits.

Name	Description
allowed_days	Type: (integer or string)[] The list of days allowed to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
denied_days	Type: (integer or string)[] The list of days denied to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
drop	Type: number Penalty for missing to visit of this type. Overrides `location.penalty.drop` value. More information
preferred_days	Type: (integer or string)[] The list of days preferred to visit the location. Dates in the YYYY-MM-DD format, numbers of days from the start of planning and names of days of the week in English with a capital letter are allowed. More information
service_duration_s	Type: number Handling time at the location. Overrides `location.service_duration_s` value. More information
title	Type: string Visits title (type). More information

initial_routes_route_element

Route node, contains information about a visited location or a work break, transit information and arrival time. More information

Name	Description
node*	Type: initial_route_node_location A representation of a location in `initial_routes`. More information
actual_arrival_time_s	Type: number or string Actual arrival time at the location. More information
actual_departure_time_s	Type: number or string Actual time of departure from the location. More information
actual_service_start_time_s	Type: number or string Actual time of service start in the location. More information
arrival_time_s	Type: number or string Arrival time at the location. If the employee arrived at the location before the visit window, it is added to the waiting time. More information
departure_time_s	Type: number or string Time of departure from the location. More information
multi_order	Type: boolean A location is one of several locations at exactly the same address which are served together. Arrival time is the same for all visits in the group, also the visits share `shared_service_duration_s`. Total service duration of all visits in multi-location group is computed as: max(`shared_service_duration_s`) + sum(`service_duration_s`). Default: `false`
waiting_duration_s	Type: number Waiting duration, time spent at location after arrival and before the start of the time window, seconds.

route_metrics

Metrics for a single route.

Name	Description
accomplished_visits*	Type: integer Total number of location visits, made by all employees.
affecting_utilization*	Type: number Ratio of total employees working time, including travel time, spent on location visits, according to their service_duration_s.
daily_proximity*	Type: number Proximity level of daily runs: average possible distance from the last location in day run, to other locations visited on the same day, kilometers.
early_location_count*	Type: integer Number of locations where arrival will happen earlier than the picked time window.
failed_time_window_location_count*	Type: integer Number of locations where arrival will happen outside of the time window.
general_utilization*	Type: number Ratio of total employees working shifts length to their total, working time, including travel time.
late_location_count*	Type: integer Number of locations where arrival will happen later than the picked time window.
overtime_duration_penalty*	Type: number Sum of per minute penalties applied for violating of maximal shift duration.
overtime_duration_s*	Type: number Total shift overtime duration in seconds.
overtime_penalty*	Type: number Sum of penalties applied for violating of maximal shift duration.
overtime_runs_count*	Type: integer Number of shifts where duration is more than `max_duration_s`.
overtime_runs_count_penalty*	Type: number Sum of fixed penalties applied for violating of maximal shift duration.
regular_time_runs_count*	Type: integer Number of routes, not violating working day duration limits.
regular_time_runs_duration_s*	Type: number Total duration of the routes, not violating working day duration limits, in seconds.
total_cost*	Type: number Total of all expenses.
total_cost_with_penalty*	Type: number Total expectation of all expenses including guaranteed and probable penalties.
total_daily_proximity_distance_m*	Type: number Total daily proximity distance: total distance from the last location in each run to other locations in the same run, meters.More information
total_daily_proximity_duration_s*	Type: number Total daily proximity duration: total duration from the last location in each run to other locations in the same run, meters.
total_daily_proximity_penalty*	Type: number Sum of daily proximity penalties.
total_duration_cost*	Type: number Total cost for all employees involved.More information
total_duration_s*	Type: number Total duration including transit, service and waiting time, seconds.
total_early_count*	Type: integer Total number of arrivals earlier than the picked time window.
total_early_duration_s*	Type: number Total duration of early arrivals, sum of (start of the time window) - (arrival time), seconds.
total_early_penalty*	Type: number Sum of penalties applied for arriving and serving at location earlier than the picked time window.
total_employee_locations_cost*	Type: number Total of all used employees costs per location.
total_failed_time_window_count*	Type: integer Total number of time window fails (sum of `total_early_count` and `total_late_count`).
total_failed_time_window_duration_s*	Type: number Total duration of time window fails (sum of `total_early_duration_s` and `total_late_duration_s`), seconds.
total_failed_time_window_penalty*	Type: number Total penalties applied for being at a location outside the visit window.
total_fixed_cost*	Type: number Total of all used employees fixed costs.
total_guaranteed_penalty*	Type: number Total of all guaranteed penalties.
total_late_count*	Type: integer Total number of arrivals later than the picked time window.
total_late_duration_s*	Type: number Total duration of late arrivals, sum of (arrival time) - (end of the time window), seconds.
total_late_penalty*	Type: number Sum of penalties applied for arriving and serving at location later than the picked time window.
total_mileage_penalty*	Type: number Total penalties applied for mileage limit violation.
total_optional_tags_cost*	Type: number The value added to the total cost by optional tags.
total_optional_zones_cost*	Type: number The value added to the total cost by optional zones.
total_penalty*	Type: number Sum of guaranteed and probable penalties.
total_runs_cost*	Type: number Total of all used employees costs per run.
total_service_duration_s*	Type: number Total duration of service at locations, seconds
total_stop_count_penalty*	Type: number Total penalties applied for stop count limit violation.
total_transit_distance_cost*	Type: number Total of all used employees costs per transit distance.
total_transit_distance_m*	Type: number Total transit distance, meters. If `routing_mode` is set to `transit`, only pedestrian distance part of routes is considered.
total_transit_duration_s*	Type: number Total transit duration (driving duration), seconds.
total_unfeasibility_penalty*	Type: number Sum of location drop penalties applied for locations which violate strict constraints but cannot be dropped.
total_waiting_duration_s*	Type: number Total duration of waiting at locations before travel to other locations or the start of the time window, seconds.More information
undertime_duration_penalty*	Type: number Sum of per minute penalties applied for violating of minimal shift duration.
undertime_duration_s*	Type: number Total shift undertime duration in seconds.
undertime_penalty*	Type: number Sum of penalties applied for violating of minimal shift duration.
undertime_runs_count*	Type: integer Number of shifts where duration is less than `min_duration_s`.
undertime_runs_count_penalty*	Type: number Sum of fixed penalties applied for violating of minimal shift duration.
route_custom_cost	Type: number Cost of custom defined expenses for route. For employees, the entire cost placed in metrics of route first run.
route_payout	Type: number Payout to employee of custom defined expenses for route. For employees, the entire payout placed in metrics of route first run.More information
run_custom_cost	Type: number Cost of custom defined expenses for run.
run_payout	Type: number Payout to employee of custom defined expenses for run.More information
total_custom_cost	Type: number Total cost of all custom defined expenses. Includes expenses for the route, shifts and runs. For employees, the entire route cost placed in metrics of first run.
total_multiorders_penalty	Type: number Total penalty for extra visits to multiorder points.More information
total_payout	Type: number Total amount of payouts to employees. For employees, the entire payment for the route placed in metrics of first run.More information
total_public_transport_distance_cost	Type: number Total of all employees costs for public transport usage distance (only pedestrian distance part of routes is actually considered).More information
total_public_transport_distance_m	Type: number Total public transport transit distance, meters (only pedestrian distance part of routes is actually considered).More information
total_public_transport_duration_cost	Type: number Total of all employees costs for public transport usage duration.More information
total_public_transport_duration_s	Type: number Total public transport usage duration, seconds.More information
total_public_transport_edges_cost	Type: number Total of all employees costs for transits between consucutive locations, using public transport.More information
total_public_transport_runs_cost	Type: number Total of all employees costs for all working days, when public transport is used.More information
total_units	Type: number Total weight of orders in the route in units.

zones_geometry

Name

Description

coordinates

Type: number[][][]

Always consists of two elements: longitude and latitude.More information

type

Type: string

Always equals Polygon

locations_cost_additional_visitors

Constituents of the locations service cost if it was visited by several employees. More information

Name

Description

fixed

Type: number

Fixed cost applied if the location is visited by more than one employees. More information

Default: 0

per_visitor

Type: number

Cost for each additional employee, visiting a location. More information

Default: 0

penalty_drop_0

Penalty if there was not a single visit to a location. In case of use, it is forbidden to use the visit_count part of location penalty.

Name	Description
all	Type: number Penalty if there was not a single visit to a location. More information Default: `0`
fixed	Type: number Fixed penalty applied if the location is visited more or less times than required.More information Default: `1000000`
per_visit	Type: number Penalty for each excessive of missing location visit. More information Default: `1000000`

locations_penalty_early

Constituents of penalties for violation of handling time — early visit to a location (used instead of the out_of_time penalty).More information

Name

Description

fixed

Type: number

Fixed penalty for violation of handling time — visiting a location earlier than the specified visit window.More information

Default: 1000

minute

Type: number

Penalty for every minute of early attendance if handling time started earlier than the specified visit window.More information

Default: 17

locations_penalty_late

Penalty components for late visits (used instead of out_of_time penalty). Whether the start or the end of service during the visit is used to penalize for lateness is determined by the penalize_late_service option.More information

Name

Description

fixed

Type: number

Fixed penalty applied if the location is visited after the end of the time window.More information

Default: 1000

minute

Type: number

Penalty for every minute of delay if a location is visited after the specified visit window.More information

Default: 17

locations_penalty_max_days_between_visits

Penalty components for the violation of days between visits requirement. More information

Name

Description

fixed

Type: number

Fixed penalty applied if the time past between two location visits is more than required. More information

Default: 0

per_day

Type: number

Penalty for each excessive day between location visits. More information

Default: 10000

locations_penalty_max_distinct_visitors

Penalty components for having location visited by more distinct employees, than specified in max_distinct_visitors option. More information

Name

Description

fixed

Type: number

Fixed penalty applied if the location is visited by more distinct employees, than specified in max_distinct_visitors option. More information

Default: 0

per_visitor

Type: number

Penalty for each excessive employee, visiting a location. More information

Default: 0

locations_penalty_min_days_between_visits

Penalty components for the violation of days between visits requirement. More information

Name

Description

fixed

Type: number

Fixed penalty applied if the time past between two location visits is less than required. More information

Default: 0

per_day

Type: number

Penalty for each missing day between location visits. More information

Default: 10000

locations_penalty_out_of_time

Penalty components for time window failure. Can be used to set the values of early and late options simultaneously, and each value is overridden if the respective option is also defined.More information

Name

Description

fixed

Type: number

Fixed penalty for visiting a location earlier or later than the specified visit window. See the specifications of early and late options for more details in each case.More information

Default: 1000

minute

Type: number

Penalty for every minute of being late or for visiting a location before the specified visit window. See the specifications of early and late options for more details in each case.More information

Default: 17

locations_penalty_preferred_days

Penalty components for failing to visit location on some of the week days, specified in preferred_days option. More information

Name

Description

fixed

Type: number

Fixed penalty applied if the location is not visited on some of the days, specified in preferred_days option, for the whole planning period. More information

Default: 0

per_day

Type: number

Penalty for each day in preferred_days, when location was not visited. More information

Default: 0

locations_penalty_visit_count

Constituents of penalties for missed visits to a location. More information

Name

Description

fixed

Type: number

Fixed penalty applied if the location is visited more or less times than required. More information

Default: 1000000

per_visit

Type: number

Penalty for each excessive of missing location visit. More information

Default: 1000000

solver_options_mvrp_1_penalty_multiorders

Penalty components for extra visits to addresses with several locations.More information

Name	Description
per_extra_employee	Type: number Penalty for every extra employees that arrives at address with several locations.More information Default: `0` Min value: `0`
per_extra_point	Type: number Penalty for every address where employees arrive more than once.More information Default: `0` Min value: `0`
per_extra_visit	Type: number Penalty for each extra visit to address with several locations.More information Default: `0` Min value: `0`

working_days_start_time_0_item

Name

Description

time_window*

Type: string

Allowed time window to visit location, in [D.]HH[:MM[:SS]] - [D.]HH[:MM[:SS]] format.More information

hard_time_window

Type: string

employee_working_days_penalty

Penalties for shift constraints violation. More information

Name	Description
early	Type: working_days_penalty_early Penalty components for shifts started too early (used instead of `out_of_time` penalty). If the shift was also finished too early, it is applied to the shift finish too.
late	Type: working_days_penalty_late Penalty components for shifts finished too late (used instead of `out_of_time` penalty). The penalty is applied both for the late end of a working day and for exceeding the maximum duration of a working day (`max_duration_s`). If both are violated simultaneously, the penalty is applied twice and summed. If the employee started their working day later than the time indicated in the `max_finish_time` parameter, in addition to this penalty, a penalty for the late start of a working day is also applied. More information
max_mileage	Type: working_days_penalty_max_mileage Penalties applied for exceeding the maximum allowed distance traveled by an employee in a working day (the `max_mileage_km` parameter).More information
out_of_time	Type: working_days_penalty_out_of_time Penalty components for time window failure. Can be used to set the values of `early` and `late` options simultaneously, and each value is overridden if the respective option is also defined.More information
stop_excess	Type: working_days_penalty_stop_excess Penalties applied for violating shifts `maximal_stops` limit.More information
stop_lack	Type: working_days_penalty_stop_lack Penalties applied for violating shifts `minimal_stops` limit.More information

initial_dropped_locations_cost_additional_visitors

Constituents of the locations service cost if it was visited by several employees. More information

Name

Description

fixed

Type: number

Fixed cost applied if the location is visited by more than one employees. More information

Default: 0

per_visitor

Type: number

Cost for each additional employee, visiting a location. More information

Default: 0

penalty_drop_0_1

Penalty if there was not a single visit to a location. In case of use, it is forbidden to use the visit_count part of location penalty.

Name	Description
all	Type: number Penalty if there was not a single visit to a location. More information Default: `0`
fixed	Type: number Fixed penalty applied if the location is visited more or less times than required.More information Default: `1000000`
per_visit	Type: number Penalty for each excessive of missing location visit. More information Default: `1000000`

initial_dropped_locations_penalty_early

Constituents of penalties for violation of handling time — early visit to a location (used instead of the out_of_time penalty).More information

Name

Description

fixed

Type: number

Fixed penalty for violation of handling time — visiting a location earlier than the specified visit window.More information

Default: 1000

minute

Type: number

Penalty for every minute of early attendance if handling time started earlier than the specified visit window.More information

Default: 17

Name

Description

fixed

Type: number

Fixed penalty for visiting a location earlier or later than the specified visit window. See the specifications of early and late options for more details in each case.More information

Default: 1000

minute

Type: number

Default: 17

initial_dropped_locations_penalty_preferred_days

Penalty components for failing to visit location on some of the week days, specified in preferred_days option. More information

Name

Description

fixed

Type: number

Fixed penalty applied if the location is not visited on some of the days, specified in preferred_days option, for the whole planning period. More information

Default: 0

per_day

Type: number

Penalty for each day in preferred_days, when location was not visited. More information

Default: 0

initial_dropped_locations_penalty_visit_count

Constituents of penalties for missed visits to a location. More information

Name

Description

fixed

Type: number

Fixed penalty applied if the location is visited more or less times than required. More information

Default: 1000000

per_visit

Type: number

Penalty for each excessive of missing location visit. More information

Default: 1000000

Penalties applied for exceeding the maximum allowed distance traveled by an employee in a working day (the max_mileage_km parameter).More information

Name

Description

fixed

Type: number

Fixed penalty applied if a employee shift has mileage greater than max_mileage_km. More information

Default: 1000

Min value: 0

Type: number

Penalty applied per each extra kilometer when shift mileage is greater than max_mileage_km shift parameter. More information

A representation of a location in initial_routes. More information

Name	Description
id*	Type: integer or string Location ID. More information
fixed_day	Type: boolean Location can only be visited on day in which it was planned. More information Default: `false`
fixed_employee	Type: boolean Location can only be visited by the employee for whom it was planned. More information Default: `false`
type	Type: string Defines the type of location: `check-in` or `base`. `check-in`: Location to be visited. `base`: A service location that an employee can specify as the start or end point of their route using the `start_at` and `finish_at` properties. More information Default: `check-in` Enum: `check-in`, `base`
undroppable	Type: boolean Location cannot be dropped. More information Default: `false`

Responses

202 Accepted

Task has been queued for execution.

Body

application/json

{
    "estimate": 0,
    "id": "string",
    "message": "string",
    "status": "string"
}

Name	Description
id*	Type: string Task unique id.
message*	Type: string Human-readable description of task state.
status*	Type: string Task status.
estimate	Type: number Estimated time when task expected to be completed. The time estimation may change during solving process. The estimate is valid for approximately 75% of tasks (they may be ready 5-15 seconds before "estimate")Some tasks may require more time for calculation, typically this extra time is not more than 1 minute.

400 Bad Request

Invalid query parameters or body.

Body

application/json

{
    "error": {
        "incident_id": "string",
        "message": "string"
    }
}

Name

Description

error*

Type: error_1_error

Error description.

error_1_error

Error description.

Name

application/json

{
    "error": {
        "incident_id": "string",
        "message": "string"
    }
}

Name

Description

error*

Type: error_1_error

Error description.

Was the article helpful?

Overview

Get task result