Obtaining results

When planning via the API, the user requests the current status or task result using the /result/mvrp/{id} method. The response is returned as a code. RouteQ also transfers the message body in JSON format. To learn more, see the specifications page.

Estimated time to perform a request

A POST request using the /add/mvrp/{id} method (see Adding a task) returns a message about successful task queuing.

Response to a POST request

{
    "id": "<Task ID>",
    "status": {
        "estimate": <estimated time to solve the task>,
        "queued": <task queuing time>
    },
    "yt_operations": [],
    "message": "Task queued"
}

Sending the /result/mvrp/{id} GET request while the task is being solved returns a message saying that the task is in the process of being solved.

Response to a GET request

{
    "id": "<Task ID>",
    "status": {
        "estimate": <estimated time to solve the task>,
        "queued": <task queuing time>,
        "started": <start time of the solving process>,
        "matrix_downloaded": <solution matrix loading time>
    },
    "yt_operations": [],
    "message": "Task is running and available for polling",
    "matrix_statistics": {
        ...
    }
}

The date and time are displayed in Timestamp format.

POST and GET requests return an estimated time a task solution is going to take in the estimate parameter.

Tasks with under 50 orders usually take less than a minute to complete (see Request processing time).

For solving larger tasks, we recommend sending a test GET request around 30 seconds after a POST request. You can send new GET requests closer to the estimated time of task solution, but no more than once every 10 seconds.

200 response description

JSON structure

{
    "id": {
        // Unique task ID.
    },
    "status": {
        // Object containing task status changes. The keys are the statuses, and the values are the time in UNIX timestamp format.
        "matrix_downloaded": <value>,
        "queued": <value>,
        "started": <value>,
        "calculated": <value>,
        "completed": <value>
    },
    "yt_operations": [...],
    "message":  <value>,
        // Text message about the task status. It's subject to change, so use the code to get information about the task status.
    "matrix_statistics": {...},
    "result": {
        // Request result.
        "detailed_cost_metrics": [
            // Detailed metrics of route costs.
        ],
        "dropped_locations": [
            // Unassigned orders.
        ],
        "metrics": {
            // General metrics of the solution.
         },
        "options": {...},
        "routes": [
            // Array of routes.
               {...},
               {...},
               {
                  "metrics": {
                      // Metrics for a single route.
                      },
                  "route": [
                      // Array of route locations.
                      {...},
                      {...},
                      {
                      "arrival_time_s": <value>,
                      "departure_time_s": <value>,
                      "multi_order": <value>,
                      "node": {...},
                      "stop_sequence_number": <value>,
                      "transit_distance_m": <value>,
                      "transit_duration_s": <value>,
                      "violations": {...},
                      "waiting_duration_s": <value>
                      },
                      {...},
                      {...}
                    ],
                  "run_number": <value>,
                  "shift": {...},
                  "vehicle_id": <value>
               }
        ],
        "solver_status": <value>,
        "vehicles": [
            // List of cars or couriers.
        ]
    }
}

The solver_status (solution status) can take the following values:

SOLVED: The problem has been solved within the set limits.
PARTIAL_SOLVED: The problem has been solved, but some orders are still unassigned.
UNFEASIBLE: It is impossible to find a solution that satisfies all the strict limits.

Task status

You can view the current task status in the status object. While the task is being solved, requests return the task status and time estimate are returned in UNIX timestamp format. The time estimate may change. The estimate is correct approximately 75% of the time (this means tasks are solved 5-15 seconds before the estimate). For some tasks, the actual solution time may be longer than shown in the estimate (usually no more than 1 minute longer).

Note

The time in the status.estimate field depends on the amount of data being processed. Do not send repeat requests to the service before this time expires.

When a task is solved, the status.calculated parameter appears in the response. This is the time when the task was solved in UNIX timestamp format. The response also contains information about general metrics, routes, and the route list.

Note

When processing responses to check the task status, look at the response code (such as 200 or 202) instead of keys in the status object or text in the message object, because these may change.

Solution general metrics

You can view the general metrics of the resulting solution in the metrics array of the result object. The table shows the most common metrics used to analyze the solution:

Field	Description
`total_transit_distance_m`	Total mileage in meters. If the `routing_mode` parameter is set to `transit`, only the route's walking part is taken into account.
`total_duration_s`	Total trip duration in seconds.
`total_waiting_duration_s`	Total waiting time on the route in seconds.
`total_served_orders`	Total number of completed orders.
`total_cost`	Cost of the solution.
`total_penalty`	Penalty size.
`total_cost_with_penalty`	Cost of the solution, including penalties.
`total_stops`	Number of stops made by the vehicle: different destinations as visited along the route, excluding stops at the depot and garage. For example, this field also takes into account stops at locations with the `pickup`, `anchor`, and `rest_place` type, as well as others. See Order type.
`used_vehicles`	Number of vehicles used in the solution.

You can find the description of other result object metrics in the specification.

Orders that can't be delivered are listed in the dropped_locations array of the result object.

Route

You can view planned routes in the routes array of the result object. The order sequence is specified in the route array.

For each location along the route, you can view the time spent traveling to that location in the transit_duration_s field and the distance in the transit_distance_m field.

In the arrival_time_s and departure_time_s fields, you can view the planned arrival and departure times for each order, respectively. In the actual_arrival_time_s and actual_departure_time_s fields (used for additional planning), you can view the actual arrival and departure times. The time is displayed as the number of seconds from the beginning of the planning day.

If the solution contains multi-orders, then the multi_order parameter is false for the first order and true for the following ones.

The waiting_duration_s field contains the amount of time spent waiting to pick up an order after arrival.

Visualization of the result

You can view the solution on mvrp-map.

Data storage period

The data on planned routes is stored on Yandex servers for a year after the solution date.

Once the storage period expires, the data can be permanently deleted.

Contact support