Using presets

A preset is a set of settings for implementing a scenario or planning strategy. Presets are stored with RouteQ.

A preset contains parameters and their values in JSON format. Presets use the same properties and options as API requests. You can specify the names (unique IDs) of the presets you use in an API request. When you execute that request, the settings from the specified presets are used (see Including presets in the request).

Advantages of using presets:

Using presets, you can implement different planning scenarios (for example, for high or low demand, for different depots, for weekdays or weekends).
Presets can be reused, which speeds up and streamlines making API requests for route planning. For integration purposes, you can specify the preset name in the preset_id field and then update the preset with new parameters without changing the integration settings.

Each preset belongs to one of the following types:

depot: Depot settings.
location: Order settings.
vehicle: Courier or vehicle settings.
vehicle-shift: Courier shift settings.
options: Global options.

A preset of a certain type can only be included in the corresponding field of the API request. If the API request field is an array and contains several elements, each element can contain a call to the preset. An object can only contain a call to one preset.

API request structure with presets

{
   "depots": [
        {
            "id": "depot1",
            "preset_id": "depot_preset_1",
            ...
        },
    ],
    "locations": [
        {
             "id": "order1",
             "preset_id": "location_preset_1",
             ...
        },
        {
             "id": "order2",
             "preset_id": "location_preset_2",
             ...
        },
        ...
    ],
    "vehicles": [
        {
            "id": "vehicle1",
             "preset_id": "vehicle_preset_1",
             ...
             "shifts": [
                  {
                      "id": "0",
                      "preset_id": "vehicle-shift_preset_fo",
                       ...
                  },
                  ...
              ],
        },
        ...
    ],
    "options": {
        "preset_id": "options_preset_id",
        ...
     }
}

Fields that cannot be used in presets

depot:
- address
- description
- id
- point
- ref
- title
location:
- address
- client_id
- comments
- delivery_to
- delivery_to_any
- depot_id
- description
- id
- phone
- pickup_from_any
- point
- ref
- title
- type
vehicle:
- depot_id
- ending_depot_id
- finish_at
- fixed_planned_route
- global_proximity_attraction_point
- id
- imei
- fixed_work_breaks
- middle_depot_id
- phone
- planned_route
- ref
- shifts
- start_at
- starting_depot_id
- visited_locations
vehicle-shift:
- id
options:
- date
- location_groups

Note

When an API request containing a call to a preset is received, the algorithm integrates parameter values from the preset into the request text and deletes the call. The resulting request that the algorithm processes has no preset names.

Public presets

Public presets can be used by all companies, but cannot be edited.

Public presets consist of several parts with the same name, but belonging to different types (for depots, locations, vehicles, vehicles.shifts, and options). All parts of the preset should be used together, because using them separately is inefficient.

Public presets have been created for specific scenarios. Their settings are based on a large number of tasks and serve to optimize solutions for the majority of cases. For certain tasks, it may be possible to set parameters that would further improve the result.

The service currently has public preset public_minimize_mileage, whose settings are optimized for minimizing mileage.

Including presets in the request

If the same parameter is defined both in the preset and in the user's request, the user-defined value is given priority. The parameter is used in its entirety, as a single structure with all the nested fields.

For example, if the penalty.early parameter is passed in the user request, and at the same time there is an active preset with a defined penalty.late parameter, the final request will include the user-defined penalty parameter, and all of the preset's nested penalty fields will be cleared.

Example of using presets

In the example below, the courier is delivering 4 orders. The request body contains all the necessary parameters.

Request without presets

{
    "depots": [
        {
            "id": "Depot",
            "point": {
                "lat": 55.733974,
                "lon": 37.587093
            },
            "time_window": "07:00:00-22:00:00",
            "penalty": {
                "out_of_time": {
                    "fixed": 0,
                    "minute": 200
                }
            },
            "hard_window": false
        }
    ],
    "locations": [
        {
            "id": "Order 1",
            "point": {
                "lat": 55.790514,
                "lon": 37.660161
            },
            "shipment_size": {
                "weight_kg": 19
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 1",
            "penalty": {
                "out_of_time": {
                    "fixed": 0,
                    "minute": 200
                }
            },
            "hard_window": false
        },
        {
            "id": "Order 2",
            "point": {
                "lat": 55.798874,
                "lon": 37.612227
            },
            "shipment_size": {
                "weight_kg": 61
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 2",
            "penalty": {
                "out_of_time": {
                    "fixed": 0,
                    "minute": 200
                }
            },
            "hard_window": false
        },
        {
            "id": "Order 3",
            "point": {
                "lat": 55.734126,
                "lon": 37.671705
            },
            "shipment_size": {
                "weight_kg": 18
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 3",
            "penalty": {
                "out_of_time": {
                    "fixed": 0,
                    "minute": 200
                }
            },
            "hard_window": false
        },
        {
            "id": "Order 4",
            "point": {
                "lat": 55.662039,
                "lon": 37.556963
            },
            "shipment_size": {
                "weight_kg": 30
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 4",
            "penalty": {
                "out_of_time": {
                    "fixed": 0,
                    "minute": 200
                }
            },
            "hard_window": false
        }
    ],
    "vehicles": [
        {
            "capacity": {
                "weight_kg": 800
            },
            "id": "Courier 1",
            "return_to_depot": false,
            "cost": {
                "km": 60,
                "fixed": 1000
            },
            "shifts": [
                {
                    "id": "0",
                    "time_window": "08:00:00-16:00:00",
                    "penalty": {
                        "out_of_time": {
                            "fixed": 0,
                            "minute": 200
                        }
                    },
                    "hard_window": false
                }
            ]
        }
    ],
    "options": {
        "time_zone": 3,
        "date": "2023-04-28",
        "quality": "normal",
        "proximity_factor": 0.1,
        "post_optimization": true,
        "global_proximity_factor": 0.2
    }
}

Public preset public_minimize_mileage has specific values for cost, penalties, grouping, and some other settings.

Settings in the public_minimize_mileage preset

depot:

"body": {
    "penalty": {
        "out_of_time": {
            "fixed": 0,
            "minute": 200
        }
    }

location:

"body": {
    "penalty": {
        "out_of_time": {
            "fixed": 0,
            "minute": 200
            }
        },
    "hard_window": false
}

vehicle:

"body": {
    "cost": {
        "km": 60,
        "fixed": 1000
    }
}

vehicle-shift:

"body": {
    "penalty": {
        "out_of_time": {
            "fixed": 0,
            "minute": 200
        }
    }
}

options:

"body": {
    "quality": "normal",
    "proximity_factor": 0.1,
    "post_optimization": true,
    "global_proximity_factor": 0.2
}

If a request uses the public_minimize_mileage preset, the request body will be shorter.

Request with preset

{
    "depots": [
        {
            "id": "Depot",
            "preset_id": "public_minimize_mileage",
            "point": {
                "lat": 55.733974,
                "lon": 37.587093
            },
            "time_window": "07:00:00-22:00:00"
        }
    ],
    "locations": [
        {
            "id": "Order 1",
            "preset_id": "public_minimize_mileage",
            "point": {
                "lat": 55.790514,
                "lon": 37.660161
            },
            "shipment_size": {
                "weight_kg": 19
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 1"
        },
        {
            "id": "Order 2",
            "preset_id": "public_minimize_mileage",
            "point": {
                "lat": 55.798874,
                "lon": 37.612227
            },
            "shipment_size": {
                "weight_kg": 61
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 2"
        },
        {
            "id": "Order 3",
            "preset_id": "public_minimize_mileage",
            "point": {
                "lat": 55.734126,
                "lon": 37.671705
            },
            "shipment_size": {
                "weight_kg": 18
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 3"
        },
        {
            "id": "Order 4",
            "preset_id": "public_minimize_mileage",
            "point": {
                "lat": 55.662039,
                "lon": 37.556963
            },
            "shipment_size": {
                "weight_kg": 30
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 4"
        }
    ],
    "vehicles": [
        {
            "capacity": {
                "weight_kg": 800
            },
            "id": "Courier 1",
            "preset_id": "public_minimize_mileage",
            "return_to_depot": false,
            "shifts": [
                {
                    "id": "0",
                    "preset_id": "public_minimize_mileage",
                    "time_window": "08:00:00-16:00:00"
                }
            ]
        }
    ],
    "options": {
        "preset_id": "public_minimize_mileage",
        "time_zone": 3,
        "date": "2023-04-28"
    }
}

How to create a preset

You can use the interface or API methods to manage presets.

Note

The name for presets of the same type must be unique. It cannot start with public_ or contain a comma.

If you encounter any problems when creating or using presets, contact support.

Using public presets

To use presets from the master data and public presets, send a request to the resource mvrp with OAuth authorization:

curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-token>" -X POST -d <request body> https://courier.yandex.ru/api/v1/vrs/add/mvrp

In the Authorization: OAuth <your-token> header, change <your-token> to the OAuth token that you received for Track & Trace.

Warning

The path in the authorization request (with an OAuth token) is different from the path indicated in the specifications (with an API key).

Example 1

There are 20 orders and 2 couriers, public presets are not used.

As a result of planning, the length of the route is 85 km.

API request (JSON) ⋅ API response ⋅ View on map

Example 2

Same as example 1, but public preset public_minimize_mileage is used to minimize mileage.

In the request processed by the planning algorithm (to view it, follow the link below), the names of presets from the public_minimize_mileage set are replaced with the contents of these presets. To view the contents of the presets from the public_minimize_mileage set, see Example of using presets.

As a result of planning, the length of the route is 79 km.