Additional route planning
Additional planning means adding locations and visits to an already planned route with employees. This may be necessary if some locations and visits have already been assigned to routes, but you need to make changes after:
- Adding new locations that need to be visited.
- Changing requirements for visiting locations.
- Changing the list of employees who handle locations.
Note
This scenario can only be implemented using API requests.
What is passed to the additional planning task:
- A full list of locations and visits (old and new ones).
- A list of employees who can handle locations.
- Routes obtained at the previous planning iteration.
- Settings that allow changes to earlier built routes.
How to implement this scenario
During additional planning, include the locations, employees, and options objects in the request as during ordinary planning. Besides that, include the initial_routes object with information about initially planned routes. You can copy this data from the result.routes object in the API response for the first planning task. For each route, pass the following objects:
day: Number of the day in the planning period (numbering starts from 0).route: Array of locations in the route.run_number: Route number (numbering starts from 1).employee_id: Employee ID.
You can copy the whole result.routes object — extra sections, such as result.routes.metrics, will be ignored during additional planning.
Fixed routes
During additional planning, you can fix the initial planning results to leave earlier planned routes unchanged and plan new visits separately.
To fix a route, set its fixed parameter to true. Fixed routes must be placed consecutively at the beginning of the initial_routes object, without any non-fixed routes between them. If there are missed empty days (when the employee doesn't visit locations) between the routes, they will also be fixed and will remain unused in the resulting solution.
Sample code with fixed routes
This example shows fixed routes for an employee on days 0 to 5. Days 0, 1, 3, and 4 aren't used — no visits to locations are planned for the employee on these days. Visits on days 2 and 5 remain unchanged. On day 6, visits may be planned for the employee. Visits planned on day 7 can be changed or assigned to another employee. New visits can be added as well.
"initial_routes": [
{
"route": [
...
],
"employee_id": "Employee 1",
"day": 2,
"fixed": true
},
{
"route": [
...
],
"employee_id": "Employee 1",
"day": 5,
"fixed": true
},
{
"route": [
...
],
"employee_id": "Employee 1",
"day": 7
},
...
]
To fix all earlier planned routes, set fixed = true in the options object.
Sample code where all routes are fixed
"locations": [
...
],
"employees": [
...
],
"options": [
...
"fixed": true
],
"initial_routes": [
...
]
You can only fix the entire route. You can't fix parts of the route (visits to individual locations).
Fixed visits
To fix visits in a route in initial_routes, use the following parameters:
-
fixed_employee: Only the specified employee can visit the location. The visit can be rescheduled or skipped. Only all visits to the location can be fixed for the employee. -
fixed_day: The employee can visit the location only on the specified day. The visit can't be assigned to another employee or skipped. -
undroppable: The visit can't be skipped. It can be assigned to another employee or rescheduled.
You can combine these parameters.
Recommended and mandatory visit time
In the route parameter, you can specify for couriers the recommended time:
- To arrive at the location,
arrival_time_s. - To depart from the location,
departure_time_s.
If the recommended time is specified for at least one location in a route, it must be specified for all locations in this route in initial_routes.
In addition to the recommended time, you can also specify the mandatory time:
- To arrive at the location,
actual_arrival_time_s. - To start handling the location,
actual_service_start_time_s. - To depart from the location,
actual_departure_time_s.
During additional planning, the algorithm will seek to meet the recommended time. The mandatory time is guaranteed to be met.
You can specify the mandatory visit time only for locations in fixed routes. If the mandatory time is specified for at least one location in a route, it must be specified for all locations in the route. Routes with mandatory time must be placed consecutively at the beginning of the employee's routes, with no routes that don't have a specified mandatory time between them.
Locations should be listed within a route so that recommended and mandatory times are placed in non-descending order.
Note
If the employee has already started the route and visited some locations by the time the additional planning task starts, specify the actual time of the employee's visits to the locations as the mandatory time.
Examples
Example 1
In the initial planning, 2 employees handle 20 locations. The planning period is 5 days. Most of the visits are assigned to Employee1.
API request (JSON) ⋅ API response
10 more orders are added during additional planning. Initial routes aren't fixed, so visits are redistributed among 2 employees. As a result, there are no unassigned locations and visits.
API request (JSON) ⋅ API response
Example 2
The same as in example 1, but additional planning is done on the second day of the planning period. The routes completed on the first day are fixed for both employees. This leaves 10 visits (one for each of the 10 added locations) unassigned.
API request (JSON) ⋅ API response