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 attributes and options as API requests. You can specify the names (unique IDs) of the presets you use in an API request. When that request is executed, it is done using the settings from the specified presets (see Including presets in requests).

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 ID, 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 reference to a separate preset. An object can only refer 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",
        ...
     }
}

When an API request containing a reference to a preset is received, the algorithm integrates parameter values from the preset into the request text. The IDs of all applied presets are passed in a separate object of the API response.

Fields that cannot be used in presets


Preset type	Field
`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`


Preset type	Field
`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`

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


Preset type	Preset body
`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 }`


Preset type	Preset body
`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 API methods to work with 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 mvrp with authorization resource:

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

In the Authorization: Auth your-OAuth-token header, replace your-OAuth-token with the OAuth token that you obtained to work with Track & Trace.

Attention.

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.

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

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

Contact support