VRt.Universal
VEEROUTE 2024

VRt.Universal [UV] (7.9.2527)

Veeroute Support Team: servicedesk@veeroute.com License: Proprietary Terms of Service
Veeroute company website

Description

Software interface for universal trip planning.

Features

  • Ability to pick up cargo from any location
  • Possibility of unloading in any location
  • Pair orders of several types: PICKUP (loading), DROP (unloading)
  • Single requests of several types: DROP_FROM_BOX (unloading cargo that is already in the body), PICKUP_TO_BOX (cargo pickup into the body without subsequent unloading), WORK (working at the location without moving the cargo)
  • A complex order can consist of any number of orders of any type
  • Transport and performers are divided into different entities, when planning, the optimal assignment of the performer to the transport occurs
  • The transport has several boxes - each of which can accommodate cargo and has its own characteristics
  • Accounting for the compatibility of cargo with transport in terms of cargo dimensions (length, width, height, additional capacity parameters)
  • Taking into account the compatibility of the cargo-box of transport (the ability to take into account the features of the box: refrigerator, thermal bag, fasteners, etc.)
  • Substitute applications, i.e. the ability to execute one of the substitute applications, the choice of which is based on its geographic location and time window

Restrictions support

Performer restrictions:

  • Start/finish location
  • Accounting for the performer's way to the transport location
  • Performer's availability schedule is a list of time windows when the performer can move and work on locations
  • The maximum duration of the performer's work during the specified time period

Transport restrictions:

  • Start/finish location
  • Transport availability schedule is a list of time windows when the transport is available
  • The maximum route distance
  • Several boxes in the transport, each with its own parameters
  • Capacity upper limit (weight, volume, number of orders, number of demands)

Order restrictions:

  • Strict time windows
  • Ability to specify different valid time windows for a location and time windows to fulfil the desired demand
  • Accounting for the requests fulfillment order within the route
  • A list of desired time windows with different associated costs

Compatibilities

Entities are compatible if the capabilities list of one entity corresponds to the list of restrictions of another entity (example: fleet parameters corresponds to cargo parameters to be delivered).

Supported compatibilities:

Name Restrictions Features
Order - Performer order.performer_restrictions performer.performer_features
Order - Not a performer order.performer_blacklist performer.performer_features
Cargo - Box order.cargo.box_restrictions transport.box.box_features
Location - Transport location.transport_restrictions transport.transport_features
Transport - Performer transport.performer_restrictions performer.performer_features
Performer - Transport performer.transport_restrictions transport.transport_features
Order - Order order.order_restrictions order.order_features

Business rule examples:

Name Business rule example
Order - Performer The driver must have a special license to fulfil the order
Order - Not a performer The driver is in the blacklist
Cargo - Box For transportation of frozen products, a box with a special temperature profile is required
Location - Transport Restrictions on the transport height
Transport - Performer The truck driver must have the class C driving license
Performer - Transport The driver is allowed to work on a specific transport
Order - Order It is not allowed to transport fish and fruits in the same box

Cargo placement

List of possibilities of a object rotations (90 degree step):

  • ALL - can rotate by any axis
  • YAW - can yaw
  • PITCH - can pitch
  • ROLL - can roll

rotation

Trip model

A trip is described by a list of states of the performer, while at the same time the performer can be in several states (for example, being inside the working time window of a location and fulfilling an order at the same location).

The meanings of the flags responsible for the geographical location:

  • AROUND_LOCATION - the performer is located near the location - in the process of parking or leaving it.
  • INSIDE_LOCATION - the performer is located at the location.

The values ​​of the flags responsible for being in time windows:

  • INSIDE_WORKING_WINDOW - the performer is inside the working time window.
  • INSIDE_LOCATION_WINDOW - the performer is located inside the location's operating time.
  • INSIDE_EVENT_HARD_WINDOW - the performer is inside a hard time window.
  • INSIDE_EVENT_SOFT_WINDOW - the performer is inside a soft time window.

The values ​​of the flags responsible for the actions:

  • ON_DEMAND - the performer is working on the request.
  • WAITING - the performer is in standby mode.
  • RELOCATING - the performer moves to the next stop.
  • BREAK - the performer is on a break.
  • REST - the performer is on a long vacation.

An example of a route with multiple states at each point in time

time set of active flags location / order / application / event comment
10:00 INSIDE_LOCATION
AROUND_LOCATION		 2 / - / - / - starting location
10:10 RELOCATING - / - / - / - we go to the first order
10:20 AROUND_LOCATION 2 / - / - / - arrived at the first order
10:40 AROUND_LOCATION
INSIDE_LOCATION
WAITING		 2 / - / - / - parked
11:00 AROUND_LOCATION
INSIDE_LOCATION
INSIDE_LOCATION_WINDOW
WAITING
INSIDE_EVENT_HARD_WINDOW		 2 / - / - / - waited for the start of the location window and at the same time the availability of the order
11:25 AROUND_LOCATION
INSIDE_LOCATION
INSIDE_LOCATION_WINDOW
ON_DEMAND
INSIDE_WORKING_WINDOW
INSIDE_EVENT_HARD_WINDOW		 2 / 1 / 2 / 3 waited for the change of artist
11:30 AROUND_LOCATION
INSIDE_LOCATION
INSIDE_LOCATION_WINDOW
ON_DEMAND
INSIDE_WORKING_WINDOW
INSIDE_EVENT_HARD_WINDOW
INSIDE_EVENT_SOFT_WINDOW		 2 / 1 / 2 / 3 while working - a soft window happened
11:40 AROUND_LOCATION
INSIDE_LOCATION
INSIDE_LOCATION_WINDOW
INSIDE_WORKING_WINDOW		 2 / - / - / - finished working
11:45 AROUND_LOCATION
INSIDE_WORKING_WINDOW		 2 / - / - / - drove out of the parking lot
11:45 RELOCATING
INSIDE_WORKING_WINDOW		 - / - / - / - we go to the next order

Planning configuration

For each planning, it is possible to specify a planning configuration that defines the objective function, the desired quality of the routes, and the calculation speed.

The name of the scheduling configuration is passed in the trips_settings.configuration field.

Main configurations:

Title Task
optimize_distance Arrange as many orders as possible, then optimize the total mileage (the number of vehicles is selected based on the mileage), used by default
optimize_transports Place as many orders as possible, while using as little transport as possible, ceteris paribus, optimize the work time of performers
optimize_locality_grouping Place as many orders as possible, while striving to optimize the visual grouping of routes, but not their number
optimize_cars_then_distance Arrange as many orders as possible, then optimize the number of vehicles, then the mileage
optimize_time Place as many orders as possible, then optimize the total work time of performers
optimize_cars_then_time Arrange as many orders as possible, then optimize the number of transport, then the total time of the performers
optimize_money Optimize the value of "profit - costs", consists of rewards for applications and costs for performers and transports (optimized value is non-negative)

Additional configurations:

Title Task
visual_grouping Arrange as many orders as possible while using as little transport as possible and routes should be visually grouped
optimize_visual_grouping Arrange as many orders as possible, then evenly distribute orders taking into account transport accessibility zones (similar to visual_grouping, but visual grouping is calculated differently)
optimize_cars_then_locality_grouping Arrange as many orders as possible, then optimize the number of vehicles, then visually group the routes
optimize_cars_then_single_location_grouping_sequenced Place as many orders as possible, then optimize the number of machines, then reliability

In addition to the existing planning options, it is possible to create an objective function directly for the client's business processes (request configuration).

For development, it is recommended to use optimize_cars_then_distance, since this configuration does not require detailed selection of rates and order values.

Data validation

Input data validation consists of several steps, which are described below.

Validation of planning results (including the search for possible reasons why orders were not planned) is located in the analytics method.

1. Schema check

If the request does not follow the schema, then scheduling is not fully started and such an error is returned along with a 400 code in schema_errors.

We recommend validating the request against the schema (or yaml file) before sending it to the server.

2. Check for logical errors that prevent planning from continuing

Schema-correct data passes the second stage of checking for the possibility of starting planning.

An example of errors at this stage are keys leading to empty entities, or if all orders are incompatible with all performers, i.e. something that makes the planning task pointless.

These errors are returned along with a 400 code in logical_errors.

3. Check for logical errors that prevent planning from continuing

At the third stage, each entity is checked separately.

All entities that have not passed validation are cut out from the original task and are not sent for planning.

Depending on the setting of treat_warnings_as_errors, the results of this type of validation are returned to warnings either with a 400 code or with the scheduling result.

4. Checks in the planning process

Part of the checks can only be carried out in the planning process.

For example - that according to the specified tariffs and according to the current traffic forecast, it is physically impossible to reach a certain point.

The results of these checks are returned in warnings or together with the scheduling result.

Entity relationship diagram

erd

Plan

Planning - creating trips from orders, performers and transport.

Planning requests can be executed in synchronous and asynchronous mode.

To get the result of cleaning the original task, use cleaning data for planning.

Planning (ASYNC)

Starting trip planning - after loading and checking the data, the process_code is returned.

Using the process_code, you can find out calculation state and get result, and also cancel calculation and delete temporary data (otherwise they will be automatically deleted according to the ttl specified in the calculation settings).

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Launching the asynchronous planning.

required
Array of objects (location) [ 1 .. 15001 ] items unique

List of locations used for orders and shifts.

required
Array of objects (order) [ 1 .. 15001 ] items unique

List of orders that need to be completed.

required
Array of objects (performer) [ 1 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

required
Array of objects (transport) [ 1 .. 15001 ] items unique

Available transports list. Transport is used by the trip performer to fulfill orders.

Array of objects (hardlink_list) [ 0 .. 15001 ] items unique

Assignments list.

object (plan_settings)

Planning settings.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

process_code
required
string <uuid> (process_code)
Example: "11111111-2222-3333-4444-555555555555"

Process code - calculation identifier.

Request samples

Content type
application/json
Example
{
}

Response samples

Content type
application/json
{
}

Planning (SYNC)

Sync method for trip planning.

Use only for testing and manual plannings.

For production use async method.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

New planning request.

required
Array of objects (location) [ 1 .. 15001 ] items unique

List of locations used for orders and shifts.

required
Array of objects (order) [ 1 .. 15001 ] items unique

List of orders that need to be completed.

required
Array of objects (performer) [ 1 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

required
Array of objects (transport) [ 1 .. 15001 ] items unique

Available transports list. Transport is used by the trip performer to fulfill orders.

Array of objects (hardlink_list) [ 0 .. 15001 ] items unique

Assignments list.

object (plan_settings)

Planning settings.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
Array of objects (trip_list) [ 0 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

required
object or null (plan_statistics)

General statistics on the calculation result.

Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

object (unplanned_items)

Information about unplanned essences.

object (removed_items)

Information about removed essences.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Request samples

Content type
application/json
Example
{
}

Response samples

Content type
application/json
Example
{
}

Cancel calculation

Cancel calculation by the calculation identifier.

Authorizations:
ApiKeyAuth
path Parameters
process_code
required
string <uuid> (process_code)
Example: 11111111-2222-3333-4444-555555555555

Unique process identifier.

Responses

Response samples

Content type
application/json
{
}

Calculation state

Read calculation state by the calculation identifier.

Authorizations:
ApiKeyAuth
path Parameters
process_code
required
string <uuid> (process_code)
Example: 11111111-2222-3333-4444-555555555555

Unique process identifier.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Response samples

Content type
application/json
{
}

Getting the result

Getting the planning result based on the calculation identifier.

Authorizations:
ApiKeyAuth
path Parameters
process_code
required
string <uuid> (process_code)
Example: 11111111-2222-3333-4444-555555555555

Unique process identifier.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
Array of objects (trip_list) [ 0 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

required
object or null (plan_statistics)

General statistics on the calculation result.

Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

object (unplanned_items)

Information about unplanned essences.

object (removed_items)

Information about removed essences.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
Array of objects (trip_list) [ 0 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

required
object or null (plan_statistics)

General statistics on the calculation result.

Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

object (unplanned_items)

Information about unplanned essences.

object (removed_items)

Information about removed essences.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Response samples

Content type
application/json
Example
{
}

Result removal

Removal of the planning result by the calculation identifier.

Authorizations:
ApiKeyAuth
path Parameters
process_code
required
string <uuid> (process_code)
Example: 11111111-2222-3333-4444-555555555555

Unique process identifier.

Responses

Response samples

Content type
application/json
{
}

Data validation

Check data before using.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Data for validation.

required
Array of objects (location) [ 1 .. 15001 ] items unique

List of locations used for orders and shifts.

required
Array of objects (order) [ 1 .. 15001 ] items unique

List of orders that need to be completed.

required
Array of objects (performer) [ 1 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

required
Array of objects (transport) [ 1 .. 15001 ] items unique

Available transports list. Transport is used by the trip performer to fulfill orders.

Array of objects (hardlink_list) [ 0 .. 15001 ] items unique

Assignments list.

object (plan_settings)

Planning settings.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

Request samples

Content type
application/json
Example
{
}

Response samples

Content type
application/json
{
}

Data refine

Refine data before using.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Data for refine.

required
Array of objects (location) [ 1 .. 15001 ] items unique

List of locations used for orders and shifts.

required
Array of objects (order) [ 1 .. 15001 ] items unique

List of orders that need to be completed.

required
Array of objects (performer) [ 1 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

required
Array of objects (transport) [ 1 .. 15001 ] items unique

Available transports list. Transport is used by the trip performer to fulfill orders.

Array of objects (hardlink_list) [ 0 .. 15001 ] items unique

Assignments list.

object (plan_settings)

Planning settings.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
object (plan_task)

Task for planning

Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

object (removed_items)

Information about removed essences.

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Calculation of statistics on trips

Calculation of statistics for existing trips

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

New request.

required
Array of objects (location) [ 1 .. 15001 ] items unique

List of locations used for orders and shifts.

required
Array of objects (order) [ 1 .. 15001 ] items unique

List of orders that need to be completed.

required
Array of objects (performer) [ 1 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

required
Array of objects (transport) [ 1 .. 15001 ] items unique

Available transports list.

Array of objects (hardlink_list) [ 0 .. 15001 ] items unique

Assignments list.

required
Array of objects (trip) [ 1 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

object (plan_settings)

Planning settings.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
Array of objects (trip_list) [ 0 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

required
object or null (plan_statistics)

General statistics on the calculation result.

Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

object (unplanned_items)

Information about unplanned essences.

object (removed_items)

Information about removed essences.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
Example
{
}

Actualize

Trips actualization - updating the planned ETA, taking into account the facts and without changing the order of the roundabout.

Actualization takes place in three stages - verification, application of facts, updating times for failed trip states.

Use data cleaning to get the result of applying facts to the original task.

The trips received as a result of updating contain only those works that remain to be completed. Orders that cannot be completed remain assigned to the contractor and end up in the waitlist.

Data clearing:

  • Entities that are not referenced by input trips - locations, performers, transport, destinations, orders, facts - are removed from the dataset.
  • If several facts refer to one entity, only the latest one in the time field is taken into account; if the time coincides, a random one is taken into account.

Accounting for existing trips:

  • Trips are transformed into hardlink destinations - i.e. Changes of performer and transport assigned to a flight cannot be used on other trips.
  • Replacement events are removed from orders and the execution order is fixed using precedence_in_trip; if orders already had an execution order specified, it will be overwritten.

Current time tracking:

  • If the current time actualize_settings.current_time is not specified in the data, then the time the server received the request is used.
  • Only those facts that occurred before actualize_settings.current_time are taken into account.
  • If the current time is greater than the left border of the time windows of all events and shifts, then the left border is shifted to the current time.
  • The allowed delay time actualize_settings.max_delay_duration is added to the right border of the time windows of all events and shifts.
  • Soft time windows are adjusted only if the duration of the order does not allow the order to be completed within the soft window.

Accounting for the fact of changing the location NEW_LOCATION:

  • To take this fact into account, the list of locations locations must contain a new location that describes the current coordinate of the performer.
  • If the flight began (the actual time is later than the planned start time of the flight) - the transport is considered to be in the same location as the performer - i.e. start_location_key of the executor and transport is changed.
  • If the flight has not started (the actual time is before the planned start time of the flight) - only the initial location of the performer changes, the location of the transport remains from the original data.
  • If there are several facts, only the latest one in the time field is taken into account.

Accounting for the fact of order completion ORDER_DONE:

  • The order, its applications and associated locations are removed from the data for updating.
  • The cargo is considered unloaded from the transport.

Accounting for facts about partial fulfillment of orders DEMAND_START and DEMAND_DONE:

  • If all orders have been completed for an order, it is considered completed (actions are similar to processing the ORDER_DONE fact).
  • If an order has an order with the PICKUP type, then the corresponding order with the DROP type will be converted into an order with the DROP_FROM_BOX type.
  • For each flight, only one open fact DEMAND_START is allowed (closed by the fact DEMAND_DONE) - since the contractor can only fulfill one request at a time.
  • If there is a fact about work on a request that contradicts the planned order in the specified flight, this request will be completed first, then the flight will continue according to the planned order.
  • The fact about the order has higher priority than the facts about applications for this order (if the facts about applications contradict the fact about the order, they will not be taken into account).

Actualization (ASYNC)

Start updating existing trips - after loading and checking the data, the calculation identifier process_code is returned.

Using process_code you can find out calculation state and get result, and also cancel calculation and delete temporary data (otherwise they will be automatically deleted according to the ttl specified in the calculation settings).

An actualize task can be transformed into a planning task using data processing.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Starting the asynchronous actualize process.

required
Array of objects (location) [ 1 .. 15001 ] items unique

List of locations used for orders and shifts.

required
Array of objects (order) [ 1 .. 15001 ] items unique

List of orders that need to be completed.

required
Array of objects (performer) [ 1 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

required
Array of objects (transport) [ 1 .. 15001 ] items unique

Available transports list. Transport is used by the trip performer to fulfill orders.

required
Array of objects (trip) [ 1 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

Array of objects (fact_list) [ 0 .. 15001 ] items unique

Trip list. A fact is an event that has occurred that affects further trip operations.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

object (plan_settings)

Planning settings.

object (actualize_settings)

Actualize settings.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

process_code
required
string <uuid> (process_code)
Example: "11111111-2222-3333-4444-555555555555"

Process code - calculation identifier.

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Actualization (SYNC)

Sync method for trips actualization.

Use only for testing and manual plannings.

For production use async method.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

New request for actualization.

required
Array of objects (location) [ 1 .. 15001 ] items unique

List of locations used for orders and shifts.

required
Array of objects (order) [ 1 .. 15001 ] items unique

List of orders that need to be completed.

required
Array of objects (performer) [ 1 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

required
Array of objects (transport) [ 1 .. 15001 ] items unique

Available transports list. Transport is used by the trip performer to fulfill orders.

required
Array of objects (trip) [ 1 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

Array of objects (fact_list) [ 0 .. 15001 ] items unique

Trip list. A fact is an event that has occurred that affects further trip operations.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

object (plan_settings)

Planning settings.

object (actualize_settings)

Actualize settings.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
Array of objects (trip_list) [ 0 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

required
object or null (plan_statistics)

General statistics on the calculation result.

Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

object (unplanned_items)

Information about unplanned essences.

object (removed_items)

Information about removed essences.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Cancel calculation

Cancel calculation by the calculation identifier.

Authorizations:
ApiKeyAuth
path Parameters
process_code
required
string <uuid> (process_code)
Example: 11111111-2222-3333-4444-555555555555

Unique process identifier.

Responses

Response samples

Content type
application/json
{
}

Calculation state

Read calculation state by the calculation identifier.

Authorizations:
ApiKeyAuth
path Parameters
process_code
required
string <uuid> (process_code)
Example: 11111111-2222-3333-4444-555555555555

Unique process identifier.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Response samples

Content type
application/json
{
}

Getting the result

Getting the planning result based on the calculation identifier.

Authorizations:
ApiKeyAuth
path Parameters
process_code
required
string <uuid> (process_code)
Example: 11111111-2222-3333-4444-555555555555

Unique process identifier.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
Array of objects (trip_list) [ 0 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

required
object or null (plan_statistics)

General statistics on the calculation result.

Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

object (unplanned_items)

Information about unplanned essences.

object (removed_items)

Information about removed essences.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
Array of objects (trip_list) [ 0 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

required
object or null (plan_statistics)

General statistics on the calculation result.

Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

object (unplanned_items)

Information about unplanned essences.

object (removed_items)

Information about removed essences.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Response samples

Content type
application/json
{
}

Result removal

Removal of the planning result by the calculation identifier.

Authorizations:
ApiKeyAuth
path Parameters
process_code
required
string <uuid> (process_code)
Example: 11111111-2222-3333-4444-555555555555

Unique process identifier.

Responses

Response samples

Content type
application/json
{
}

Data validation

Check data before using.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Data for validation.

required
Array of objects (location) [ 1 .. 15001 ] items unique

List of locations used for orders and shifts.

required
Array of objects (order) [ 1 .. 15001 ] items unique

List of orders that need to be completed.

required
Array of objects (performer) [ 1 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

required
Array of objects (transport) [ 1 .. 15001 ] items unique

Available transports list. Transport is used by the trip performer to fulfill orders.

required
Array of objects (trip) [ 1 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

Array of objects (fact_list) [ 0 .. 15001 ] items unique

Trip list. A fact is an event that has occurred that affects further trip operations.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

object (plan_settings)

Planning settings.

object (actualize_settings)

Actualize settings.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Data refine

Refine data before using.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Data for refine.

required
Array of objects (location) [ 1 .. 15001 ] items unique

List of locations used for orders and shifts.

required
Array of objects (order) [ 1 .. 15001 ] items unique

List of orders that need to be completed.

required
Array of objects (performer) [ 1 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

required
Array of objects (transport) [ 1 .. 15001 ] items unique

Available transports list. Transport is used by the trip performer to fulfill orders.

required
Array of objects (trip) [ 1 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

Array of objects (fact_list) [ 0 .. 15001 ] items unique

Trip list. A fact is an event that has occurred that affects further trip operations.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

object (plan_settings)

Planning settings.

object (actualize_settings)

Actualize settings.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
object (plan_task)

Task for planning

Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

object (removed_items)

Information about removed essences.

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Replan

Replanning - creation of new trips based on existing trips, taking into account the facts.

Replanning takes place in three stages - checking, applying facts and creating restrictions for planning based on existing trips, planning.

Replanning (ASYNC)

Starting trip replanning - changing existing and creating new trips based on the facts and data about orders, performers and transport.

After loading and checking the data, the process_code is returned.

Using the process_code, you can find out calculation state and get result, and also cancel calculation and delete temporary data (otherwise they will be automatically deleted according to the ttl specified in the calculation settings).

An replan task can be transformed into a plan task using data processing.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Launching the asynchronous replanning.

required
Array of objects (location) [ 1 .. 15001 ] items unique

List of locations used for orders and shifts.

required
Array of objects (order) [ 1 .. 15001 ] items unique

List of orders that need to be completed.

required
Array of objects (performer) [ 1 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

required
Array of objects (transport) [ 1 .. 15001 ] items unique

Available transports list.

Array of objects (hardlink_list) [ 0 .. 15001 ] items unique

Assignments list.

required
Array of objects (trip) [ 1 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

Array of objects (fact_list) [ 0 .. 15001 ] items unique

Trip list. A fact is an event that has occurred that affects further trip operations.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

object (plan_settings)

Planning settings.

object (replan_settings)

Replanning settings.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

process_code
required
string <uuid> (process_code)
Example: "11111111-2222-3333-4444-555555555555"

Process code - calculation identifier.

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Replanning (SYNC)

Sync method for trips replanning.

Use only for testing and manual plannings.

For production use async method.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

New replanning request.

required
Array of objects (location) [ 1 .. 15001 ] items unique

List of locations used for orders and shifts.

required
Array of objects (order) [ 1 .. 15001 ] items unique

List of orders that need to be completed.

required
Array of objects (performer) [ 1 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

required
Array of objects (transport) [ 1 .. 15001 ] items unique

Available transports list.

Array of objects (hardlink_list) [ 0 .. 15001 ] items unique

Assignments list.

required
Array of objects (trip) [ 1 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

Array of objects (fact_list) [ 0 .. 15001 ] items unique

Trip list. A fact is an event that has occurred that affects further trip operations.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

object (plan_settings)

Planning settings.

object (replan_settings)

Replanning settings.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
Array of objects (trip_list) [ 0 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

required
object or null (plan_statistics)

General statistics on the calculation result.

Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

object (unplanned_items)

Information about unplanned essences.

object (removed_items)

Information about removed essences.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Cancel calculation

Cancel calculation by the calculation identifier.

Authorizations:
ApiKeyAuth
path Parameters
process_code
required
string <uuid> (process_code)
Example: 11111111-2222-3333-4444-555555555555

Unique process identifier.

Responses

Response samples

Content type
application/json
{
}

Calculation state

Read calculation state by the calculation identifier.

Authorizations:
ApiKeyAuth
path Parameters
process_code
required
string <uuid> (process_code)
Example: 11111111-2222-3333-4444-555555555555

Unique process identifier.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Response samples

Content type
application/json
{
}

Getting the result

Getting the replanning result based on the calculation identifier.

Authorizations:
ApiKeyAuth
path Parameters
process_code
required
string <uuid> (process_code)
Example: 11111111-2222-3333-4444-555555555555

Unique process identifier.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
Array of objects (trip_list) [ 0 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

required
object or null (plan_statistics)

General statistics on the calculation result.

Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

object (unplanned_items)

Information about unplanned essences.

object (removed_items)

Information about removed essences.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
Array of objects (trip_list) [ 0 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

required
object or null (plan_statistics)

General statistics on the calculation result.

Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

object (unplanned_items)

Information about unplanned essences.

object (removed_items)

Information about removed essences.

calculation_progress
required
integer <int32> (calculation_progress) [ 0 .. 100 ]
Example: "52"

Calculation progress as a percentage. The progress displays the current number of completed steps.

required
object (calculation_info)

Calculation information.

Response samples

Content type
application/json
{
}

Result removal

Removal of the planning result by the calculation identifier.

Authorizations:
ApiKeyAuth
path Parameters
process_code
required
string <uuid> (process_code)
Example: 11111111-2222-3333-4444-555555555555

Unique process identifier.

Responses

Response samples

Content type
application/json
{
}

Data validation

Check data before using.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Data for validation.

required
Array of objects (location) [ 1 .. 15001 ] items unique

List of locations used for orders and shifts.

required
Array of objects (order) [ 1 .. 15001 ] items unique

List of orders that need to be completed.

required
Array of objects (performer) [ 1 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

required
Array of objects (transport) [ 1 .. 15001 ] items unique

Available transports list.

Array of objects (hardlink_list) [ 0 .. 15001 ] items unique

Assignments list.

required
Array of objects (trip) [ 1 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

Array of objects (fact_list) [ 0 .. 15001 ] items unique

Trip list. A fact is an event that has occurred that affects further trip operations.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

object (plan_settings)

Planning settings.

object (replan_settings)

Replanning settings.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Data refine

Refine data before using.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Data for refine.

required
Array of objects (location) [ 1 .. 15001 ] items unique

List of locations used for orders and shifts.

required
Array of objects (order) [ 1 .. 15001 ] items unique

List of orders that need to be completed.

required
Array of objects (performer) [ 1 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

required
Array of objects (transport) [ 1 .. 15001 ] items unique

Available transports list.

Array of objects (hardlink_list) [ 0 .. 15001 ] items unique

Assignments list.

required
Array of objects (trip) [ 1 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

Array of objects (fact_list) [ 0 .. 15001 ] items unique

Trip list. A fact is an event that has occurred that affects further trip operations.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

object (plan_settings)

Planning settings.

object (replan_settings)

Replanning settings.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: application/json
required
object (tracedata)

Data for request tracing.

required
object (plan_task)

Task for planning

Array of objects (entity_warning_list) [ 0 .. 15001 ] items

Warning list.

object (removed_items)

Information about removed essences.

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Convert

Data conversion.

JSON >> XLSX

Used for conversion of data to the VRt.Universal XLSX format.

Authorizations:
ApiKeyAuth
query Parameters
timezone
integer <int32> (timezone) [ -12 .. 12 ]
Default: 0
Example: timezone=3

Target time zone.

Request Body schema: application/json
required

Conversion request to the XLSX.

Array of objects (location_list) [ 0 .. 15001 ] items unique

List of locations used for orders and shifts.

Array of objects (order_list) [ 0 .. 15001 ] items unique

List of orders that need to be completed.

Array of objects (performer_list) [ 0 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

Array of objects (transport_list) [ 0 .. 15001 ] items unique

Available transports list. Transport is used by the trip performer to fulfill orders.

Array of objects (hardlink_list) [ 0 .. 15001 ] items unique

Assignments list.

Array of objects (trip_list) [ 0 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

Array of objects (fact_list) [ 0 .. 15001 ] items unique

Trip list. A fact is an event that has occurred that affects further trip operations.

object or null (plan_statistics)

General statistics on the calculation result.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

object (plan_settings)

Planning settings.

object (replan_settings)

Replanning settings.

object (actualize_settings)

Actualize settings.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: application/octet-stream
string <byte> (file_xlsx)

File with data in XLSX format.

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

XLSX >> JSON

Used for data conversion from the VRt.Universal XLSX format to the VRt.Universal JSON format.

Authorizations:
ApiKeyAuth
Request Body schema: application/octet-stream
required

Conversion request to the JSON format.

string <byte> (file_xlsx)

File with data in XLSX format.

Responses

Response Schema: application/json
Array of objects (location_list) [ 0 .. 15001 ] items unique

List of locations used for orders and shifts.

Array of objects (order_list) [ 0 .. 15001 ] items unique

List of orders that need to be completed.

Array of objects (performer_list) [ 0 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

Array of objects (transport_list) [ 0 .. 15001 ] items unique

Available transports list. Transport is used by the trip performer to fulfill orders.

Array of objects (hardlink_list) [ 0 .. 15001 ] items unique

Assignments list.

Array of objects (trip_list) [ 0 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

Array of objects (fact_list) [ 0 .. 15001 ] items unique

Trip list. A fact is an event that has occurred that affects further trip operations.

object or null (plan_statistics)

General statistics on the calculation result.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

object (plan_settings)

Planning settings.

object (replan_settings)

Replanning settings.

object (actualize_settings)

Actualize settings.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Response samples

Content type
application/json
{
}

JSON >> THRIFT

Used for conversion of input data to the THRIFT format.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Conversion request to the THRIFT.

Array of objects (location_list) [ 0 .. 15001 ] items unique

List of locations used for orders and shifts.

Array of objects (order_list) [ 0 .. 15001 ] items unique

List of orders that need to be completed.

Array of objects (performer_list) [ 0 .. 15001 ] items unique

Available performers list. The performer fulfills orders using transport.

Array of objects (transport_list) [ 0 .. 15001 ] items unique

Available transports list. Transport is used by the trip performer to fulfill orders.

Array of objects (hardlink_list) [ 0 .. 15001 ] items unique

Assignments list.

Array of objects (trip_list) [ 0 .. 15001 ] items unique

Trip list. A trip is a set of works planned to be performed by a specific performer on a specific transport, expressed through a change in the states of the performer.

Array of objects (fact_list) [ 0 .. 15001 ] items unique

Trip list. A fact is an event that has occurred that affects further trip operations.

object or null (plan_statistics)

General statistics on the calculation result.

Array of objects (routing_transport_matrix_list) [ 0 .. 16 ] items unique

List of matrices of times and distances for each type of transport that are indicated in the data. The matrix should describe all locations for each type of transport from the data. When specifying an external routing matrix external_routing, the geo_settings parameters are not taken into account.

object (plan_settings)

Planning settings.

object (replan_settings)

Replanning settings.

object (actualize_settings)

Actualize settings.

dataset_name
string (dataset_name) [ 0 .. 512 ] characters
Example: "custom_dataset_one"

The name of the dataset. A technical field that does not affect calculation.

Responses

Response Schema: text/plain
string (file_text)

File with data in text format.

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

System

System functions. Auxiliary functionality common to all services.

Checking the availability

Checking the service availability.

Responses

Response Schema: application/json
health
required
number <double> [ 0 .. 1 ]
Example: "0.999"

The current health indicator of the service.

  • 0.0 means the service is not ready to perform tasks.
  • 1.0 means the service is fully ready to perform tasks.

Response samples

Content type
application/json
{
}

Getting the service version

Getting the service version.

Responses

Response Schema: application/json
major
required
integer <int32> [ 1 .. 100 ]
Example: "7"

Product version. Within a single version, compatibility of common data structures between services is guaranteed. A version change indicates changes that are incompatible with previous versions of the product (and all services).

minor
required
integer <int32> [ 0 .. 111 ]
Example: "5"

Minor version of the service. A version change indicates new functionality. The update is backward compatible with the major version of the service.

build
required
string [ 1 .. 64 ] characters
Example: "3754RC"

Build version.
Contains backwards compatible bug fixes and docs update.

Response samples

Content type
application/json
{
}

Getting the documentation

Getting the file with this service documentation.

path Parameters
filename
required
string [ 6 .. 128 ] characters
Example: file_en.html

File name.

Responses

Response Schema:
string (file_html)

File with data in HTML format.

Response samples

Content type
application/json
{
}

XLSX Format

Description of VRt.Universal XLSX format for import / data export.

This format is a complete display of data JSON models and is used for:

  • initial data
  • process settings
  • calculation results
  • statistics on the calculation result

Below is a description of each sheet separately.

Data settings

The name of the sheet info.

Title Description
api_version API version at the time of XLSX generation
timezone Time zone, used in all times in the data
docs_ru Link to documentation (RU)
docs_en Link to documentation (EN)
docs_zh Link to documentation (ZH)

Locations

The name of the sheet locations.

List of locations that are used in orders and shifts.

The described object:

key
required
string [ 1 .. 1024 ] characters
Example: "location_01"

Location key, unique identifier.

required
object (geopoint)

Geographical point.

arrival_duration
string <duration> (time_duration) [ 3 .. 16 ] characters ^P(?!$)((\d+Y)|(\d+\.\d+Y$))?((\d+M)|(\d+\.\d...
Example: "PT1H45M"

Time for driving up to the location (or waiting time at parking lot) according to ISO 8601 duration.

departure_duration
string <duration> (time_duration) [ 3 .. 16 ] characters ^P(?!$)((\d+Y)|(\d+\.\d+Y$))?((\d+M)|(\d+\.\d...
Example: "PT1H45M"

Time to leave the location according to ISO 8601 duration.

Array of objects (location_timetable) [ 0 .. 30 ] items

Location timetable - time windows of availability and capacity restrictions. If the list is empty or not specified, the location works without restrictions.

object or null (location_compatibilities)

Location compatibilities.

Array of objects (attributes) [ 0 .. 1000 ] items unique

Attributes. Used to add service information.

{
}

Performers

The name of the sheet is performers.

List of available performers.

The described object:

key
required
string [ 1 .. 1024 ] characters
Example: "performer0001"

Performer's key, unique identifier.

required
Array of objects (performer_shift) [ 1 .. 15001 ] items unique

List of working shifts of performer.

own_transport_type
string (transport_type)
Enum: "CAR" "TRUCK_1500" "TRUCK_3000" … 13 more
Example: "CAR"

The type of personal transport that the performer will use to get to his assigned work transport.

object or null (performer_compatibilities)

Performer compatibilities.

object or null (performer_limits)

The performer limitations.

Array of objects (attributes) [ 0 .. 1000 ] items unique

Attributes. Used to add service information.

{
}

Transports

The name of the sheet transports.

List of available transport.

The described object:

key
required
string [ 1 .. 1024 ] characters
Example: "transport001"

Transport key, unique identifier.

required
Array of objects (transport_shift) [ 1 .. 15001 ] items unique

List of working shifts of transport.

transport_type
string (transport_type)
Enum: "CAR" "TRUCK_1500" "TRUCK_3000" … 13 more
Example: "CAR"

Transport types:

  • CAR - car
  • TRUCK_1500 - truck with permissible weight 1500 kg
  • TRUCK_3000 - truck with permissible weight 3000 kg
  • TRUCK_5000 - truck with permissible weight 5000 kg
  • TRUCK_10000 - truck with permissible weight 10000 kg
  • TRUCK_20000 - truck with permissible weight 20000 kg
  • TRUCK_10000_L75_H35_W24_6000 - a truck with a permitted weight of no more than 10,000 kg, dimensions of 7.5 x 3.5 x 2.4 meters, and a permissible axle load of 6,000 kg
  • TRUCK_18000_L95_H40_W26_11000 - a truck with a permitted weight of no more than 18,000 kg, dimensions of 9.5 x 4.0 x 2.6 meters, and a permissible axle load of 11,000 kg
  • TRUCK_26000_L120_H40_W26_8000 - a truck with a permitted weight of no more than 26,000 kg, dimensions of 12.0 x 4.0 x 2.6 meters, and a permissible axle load of 8000 kg
  • TRUCK_GARBAGE_1 - truck for transporting garbage (type 1)
  • TRUCK_GARBAGE_2 - truck for transporting garbage (type 2)
  • TUK_TUK - tuk-tuk
  • BICYCLE - bicycle
  • PEDESTRIAN - pedestrian
  • PUBLIC_TRANSPORT - public transport
  • TELEPORT - teleport (instant movement between points)

Permissible weight is the weight of the equipped transport with cargo and driver, set by the manufacturer as the maximum allowable.

Array of objects (box) [ 0 .. 100 ] items unique
Default: []

A list of transport boxes that can accommodate the cargo.

object or null (transport_compatibilities)

Transport compatibilities.

object or null (transport_limits)

Transport load limits.

Array of objects (attributes) [ 0 .. 1000 ] items unique

Attributes. Used to add service information.

{
}

Boxes

The name of the sheet is transports.boxes.

List of transport boxes that can accommodate the load. The table is mandatory if there are orders with applications of types of PICKUP and DROP. In the description of the boxes, those fields that describe cargo are required.

The described object:

key
required
string [ 1 .. 1024 ] characters
Example: "box01"

Unique box key used to identify the cargo placement in boxes.

object or null (capacity)

The box capacity, which limits the maximum amount for all capacity fields of all the cargoes.

object or null (box_compatibilities)

A transport box compatibilities.

object or null (box_limits)

Box limits.

{
}

Orders

The name of the sheet is orders.

List of orders.

The described object:

key
required
string [ 1 .. 1024 ] characters
Example: "order01"

Order key, unique identifier.

required
Array of objects (demand) [ 1 .. 1000 ] items unique

Demands list.

Array of objects (cargo) [ 0 .. 1000 ] items unique
Default: []

The list of cargoes referred to by the demands of this order. The list must be empty if all demands in the order are of type WORK.

object or null (order_compatibilities)
Array of objects (attributes) [ 0 .. 1000 ] items unique

Attributes. Used to add service information.

{
}

Cargos

The name of the sheet is orders.cargos.

List of goods. It may contain one load for DROP, a list for PICKUP, empty for WORK. The table is not obligatory if all applications have the type WORK.

The described object:

key
required
string [ 1 .. 1024 ] characters
Example: "cargo01"

Cargo key, unique identifier.

object or null (capacity)

Cargo additive measures.

object or null (cargo_compatibilities)
target_box_key
string or null [ 1 .. 1024 ] characters
Default: null
Example: "box01"

The key of the transport box in which the cargo is already located. Applicable only for cargo that is in the order with the type DROP_FROM_BOX. For other order types, the key must be empty.

{
}

Trips

The name of the sheet trips.

List of trips.

The described object:

key
required
string [ 1 .. 1024 ] characters
Example: "trip-0000-9999"

Unique trip identifier.

name
string (trip_name) [ 0 .. 64 ] characters
Example: "1-ABC"

Trip name.

required
object (assigned_performer)

Performer's shift assigned to the specified time (shift_time).

required
object (assigned_transport)

Transport's shift assigned to the specified time (shift_time).

required
Array of objects (trip_state_list) [ 0 .. 15001 ] items

List of performer's states.

waitlist
Array of strings (trip_waitlist) [ 0 .. 15001 ] items unique [ items [ 1 .. 1024 ] characters ]
Example: "order02"

List of order keys assigned to the performer, but not scheduled for a specific time and not taken into account in the transport load.

Array of objects (attributes) [ 0 .. 1000 ] items unique

Attributes. Used to add service information.

{
}

Facts

The name of the sheet is facts.

List of facts.

The described object:

key
required
string [ 1 .. 1024 ] characters
Example: "fact_01"

Fact key.

time
required
string <date-time> (fact_time)
Example: "2024-11-21T09:30:00+03:00"

Fact creation time in the ISO 8601 format.

type
required
string (fact_type)
Enum: "NEW_LOCATION" "ORDER_DONE" "DEMAND_START" … 1 more
Example: "NEW_LOCATION"

Possible order (demand) fact types:

  • NEW_LOCATION - the performer changed his location during the trip
  • ORDER_DONE - the performer has finished fulfilling the order (or the order has been cancelled), the cargo associated with the order is no longer in the transport box
  • DEMAND_START - performer started to fulfill the demand
  • DEMAND_DONE - performer finished to fulfill the demand
trip_key
required
string [ 1 .. 1024 ] characters
Example: "trip_01"

Trip key, to which the fact relates.

order_key
string or null [ 1 .. 1024 ] characters
Default: null
Example: "order_01"

Order key, required for facts with type ORDER_DONE.

demand_key
string or null [ 1 .. 1024 ] characters
Default: null
Example: "order_01_demand_01"

Demand key, required for facts with types DEMAND_DONE and DEMAND_START.

performer_key
string or null [ 1 .. 1024 ] characters
Default: null
Example: "performer_01"

Performer key, required for facts with type NEW_LOCATION.

location_key
string or null [ 1 .. 1024 ] characters
Default: null
Example: "location_01"

Location key, required for facts with type NEW_LOCATION.

{
}

Plan settings

The name of the sheet plan_settings.

The described object:

object (trips_settings)

Trip creation settings.

object (geo_settings)

Geodata usage settings.

object (calculation_settings)

Calculation settings.

{
}

Actualize settings

The name of the sheet is actualize_settings.

The described object:

current_time
string or null <date-time>
Example: "2024-11-21T09:30:00+03:00"

Current date and time according to the ISO 8601. If not specified, the current time when the request was received by the server is taken.

max_delay_duration
string <duration> [ 3 .. 16 ] characters ^P(?!$)((\d+Y)|(\d+\.\d+Y$))?((\d+M)|(\d+\.\d...
Default: "PT3H"
Example: "PT1H30M"

Acceptable delay. Affects the shift of the right boundaries of hard time windows of orders and time windows of work shifts of performers and transports.

{
}

Replan settings

The name of the sheet is replan_settings.

The described object:

object (replan_strategy)

Replan strategy.

{
}

Total Statistics

The name of the sheet is total_statistics.

Total Statistics.

The described object:

cost
required
number <double> [ 0 .. 10000000000 ]
Example: "1231.1"

Total cost calculated based on the performer's and transport tariffs.

reward
required
number <double> [ 0 .. 10000000000 ]
Example: "2343.3"

The total reward for orders fulfillment.

profit
required
number <double> [ -10000000000 .. 10000000000 ]
Example: "1231.1"

The total profit is equal to the difference between the total reward (reward) and cost (cost).

required
object (measurements)

Measurements of times and distances for aggregate and individual trips:

  • time_window - the start time of the first trip and the end time of the last, if there are no trips, the time of the left border of the planning horizon is returned, while the from \ to fields have the same value
  • driving_time - duration of driving time
  • waiting_time - total waiting time for all locations
  • working_time - total time of work execution at all locations included in the trip
  • break_time - total break time for all locations
  • rest_time - total rest time for all locations
  • arriving_time - total time to drive / park at locations
  • departure_time - total time for departure from locations
  • total_time - total time, composed of driving_time + waiting_time + working_time + break_time + rest_time + arriving_time + departure_time
  • distance - the total length of the trip / set of trips, in meters
trips_count
required
integer <int32> [ 0 .. 15001 ]
Example: "250"

The total number of planned trips.

performers_count
required
integer <int32> [ 0 .. 15001 ]
Example: "157"

The total number of performers involved in orders fulfillment.

orders_count
required
integer <int32> [ 0 .. 15001 ]
Example: "1700"

The total number of planned and assigned orders.

plan_orders_count
required
integer <int32> [ 0 .. 15001 ]
Example: "1003"

The total number of planned orders.

waitlist_orders_count
required
integer <int32> [ 0 .. 15001 ]
Example: "697"

The total number of assigned orders.

stops_count
required
integer <int32> [ 0 .. 15001000 ]
Example: "87"

The total number of stops (non-unique locations).

locations_count
required
integer <int32> [ 0 .. 15001000 ]
Example: "45"

The total number of unique locations within one trip.

required
object (capacity_statistics_sum)

Total additive measures of the transported cargo.

required
object (capacity_statistics_ratio)

The ratio of the total additive measures of the transported cargo to the total capacity of the boxes. In fractions of a unit. It may be more than one.

required
object (capacity_statistics_load)

The ratio of the maximum load of boxes to the total capacity of boxes. In fractions of a unit. Cannot be greater than one.

average_speed
required
number <double> >= 0
Example: "43.1"

Average speed is the ratio of the total distance to the total time of movement, km/h.

round_trips_count
required
integer <int32> [ 0 .. 15001 ]
Example: "2"

Number of round-trips within a trip.

Array of objects (attributes) [ 0 .. 1000 ] items unique

Attributes. Used to add service information.

{
}