--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://yandex.kz/routing/doc/en/vrp/get-result.md - https://yandex.kz/routing/doc/kk/vrp/get-result.md - https://yandex.kz/routing/doc/ru/vrp/get-result.md - href: kk/vrp/get-result.md type: text/markdown title: Markdown version - href: llms.txt type: text/markdown title: llms.txt title: Яндекс Маршрутизация — интеграция с API — структура ответа --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.kz/routing/doc/kk/llms.txt # Получение результата При планировании через API пользователь запрашивает текущий статус или результат выполнения задачи с помощью метода `/mvrp/fetch-result/{task_id}`. В запросе должен передаваться [ключ API](https://yandex.kz/routing/doc/kk/vrp/authorization.md#api-key) или [OAuth-токен](https://yandex.kz/routing/doc/kk/vrp/authorization.md#oauth-token). Ответ приходит в виде кода. Сервис дополнительно передает тело сообщения в формате JSON, подробнее см. в разделе со [спецификацией](https://yandex.ru/routing/doc/ru/vrp/redoc/index.html#operation/getMVRPTaskResult). Сервис вернет ответ на том языке, который вы задали параметром `lang` при [добавлении задачи](https://yandex.kz/routing/doc/kk/vrp/add-task.md). ## Ожидаемое время выполнения запроса {#response-time} Когда пользователь отправляет POST-запрос с помощью метода `/add/mvrp/{id}` (см. раздел [Добавление задачи](https://yandex.kz/routing/doc/kk/vrp/add-task.md)), в ответе приходит сообщение о постановке задачи в очередь. {% cut "Ответ на POST-запрос" %} ```json { "id": "", "status": { "estimate": <ориентировочное время решения задачи>, "queued": <время, когда задача поставлена в очередь на решение> }, "yt_operations": [], "message": "Task queued" } ``` {% endcut %} Если во время решения задачи отправить GET-запрос `/mvrp/fetch-result/{task_id}`, в ответе приходит сообщение о том, что задача решается. {% cut "Ответ на GET-запрос" %} ```json { "id": "", "status": { "estimate": <ориентировочное время решения задачи>, "queued": <время, когда задача поставлена в очередь на решение>, "started": <время начала решения задачи>, "matrix_downloaded": <время загрузки матрицы решения> }, "yt_operations": [], "message": "Task is running and available for polling", "matrix_statistics": { ... } } ``` {% endcut %} Дата и время отображаются в формате Timestamp. В ответах на POST и GET-запросы приходит ориентировочное время решения задачи в параметре `estimate`. Если в задаче меньше 50 заказов, обычно она решается в течение одной минуты, см. [Время обработки запроса](https://yandex.kz/routing/doc/kk/vrp/request-processing-time.md). При решении больших задач рекомендуем отправлять проверочный GET-запрос примерно через 30 секунд после отправки POST-запроса. Повторные GET-запросы можно отправлять ближе к ориентировочному времени решения задачи, не чаще одного раза в 10 секунд. ## Описание ответа с кодом 200 {#response-structure} {% cut "Структура JSON" %} ```json { "id": { // Уникальный ID задачи. }, "status": { // Объект, содержащий изменения статусов задачи. Ключи — статусы, значения — время в формате UNIX timestamp. "matrix_downloaded": , "queued": , "started": , "calculated": , "completed": }, "yt_operations": [...], "message": , // Текстовое сообщение о состоянии задачи. Может меняться, поэтому для получения информации о статусе задачи необходимо использовать код. "matrix_statistics": {...}, "result": { // Результат выполнения запроса. "detailed_cost_metrics": [ // Детальные метрики стоимости маршрутов. ], "dropped_locations": [ // Нераспределенные заказы. ], "metrics": { // Общие метрики решения. }, "options": {...}, "routes": [ // Массив маршрутов. {...}, {...}, { "metrics": { // Метрики отдельного маршрута. }, "route": [ // Массив точек маршрута. {...}, {...}, { "arrival_time_s": , "departure_time_s": , "multi_order": , "node": {...}, "stop_sequence_number": , "transit_distance_m": , "transit_duration_s": , "violations": {...}, "waiting_duration_s": }, {...}, {...} ], "run_number": , "shift": {...}, "vehicle_id": } ], "solver_status": , "vehicles": [ // Список автомобилей или курьеров. ] } } ``` {% endcut %} Статус решения задачи `solver_status` может принимать следующие значения: - `SOLVED` — задача полностью решается в рамках заданных ограничений; - `PARTIAL_SOLVED` — задача решена, но некоторые заказы остались нераспределенными; - `UNFEASIBLE` — невозможно найти решение, удовлетворяющее всем строгим ограничениям. ### Статус задачи {#status} Текущий статус задачи можно посмотреть в объекте `status`. Пока задача решается, при запросе ответа возвращается ее статус и прогноз времени решения задачи `estimate` в формате UNIX timestamp. Оценочное время решения задачи может меняться в процессе решения. Оценка верна примерно в 75% случаев (задачи решаются за 5-15 секунд до `estimate`). Для некоторых задач фактическое время решения может быть больше, чем указано в `estimate` (обычно, не более чем на 3 минуты). {% note info %} Время в поле `status.estimate` зависит от количества обрабатываемых данных. Не отправляйте повторные запросы к сервису до истечения этого времени. {% endnote %} После решения задачи в ответе появляется параметр `status.calculated` — время, когда задача была решена в формате UNIX timestamp. Также в ответе отражается информация по общим метрикам, маршрутам и последовательности исполнения маршрута. {% note info %} При обработке ответов для понимания статуса задачи анализируйте код ответа (200, 202 и т. д.), но не ключи в объекте `status` и не тексты сообщений в объекте `message`, так как они могут меняться. {% endnote %} ### Общие метрики полученного решения {#common-metrics} Общие метрики полученного решения можно посмотреть в массиве `metrics` объекта `result`. В таблице представлены метрики, которые чаще всего используются для анализа решения: #| ||**Поле** | **Описание**|| ||`total_transit_distance_m` | Общий пробег в метрах. Если параметр `routing_mode` установлен в `transit`, то учитывается только пешеходная часть маршрута.|| ||`total_duration_s` | Общая длительность поездок в секундах.|| ||`total_waiting_duration_s` | Общее ожидание на маршруте в секундах.|| ||`total_served_orders` | Общее количество выполненных заказов.|| ||`total_cost` | Стоимость решения. См. раздел [Алгоритм маршрутизации](https://yandex.kz/routing/doc/kk/vrp/routing-algorithm.md).|| ||`total_penalty` | Размер штрафов. См. раздел [Информация о штрафах при маршрутизации](https://yandex.kz/routing/doc/kk/vrp/more-about-penalties.md).|| ||`total_cost_with_penalty` | Стоимость решения, включая штрафы. См. раздел [Алгоритм маршрутизации](https://yandex.kz/routing/doc/kk/vrp/routing-algorithm.md).|| ||`total_stops` | Количество остановок транспортного средства — различных точек назначения в порядке их посещения по маршруту, исключая заезды на склад и в гараж. Например, в этом поле учитываются также остановки в точках с типом `pickup`, `anchor`, `rest_place` и др. См. раздел [Тип заказа](https://yandex.kz/routing/doc/kk/vrp/properties-of-orders.md#order-type).|| ||`used_vehicles` | Количество транспортных средств, используемых в решении.|| |# Описание остальных метрик объекта `result` вы найдете в [спецификации](https://yandex.ru/routing/doc/ru/vrp/redoc/index.html#operation/getMVRPTaskResult). Если какие-то заказы не могут быть доставлены, они перечисляются в массиве `dropped_locations` объекта `result`. Для каждого нераспределенного заказа в поле `drop_reason` содержится информация о причине нераспределения. [Детальная информация о причинах нераспределения](https://yandex.kz/routing/doc/kk/vrp/routes-with-drops.md#detailed-drop-reasons) отобразится, если при [добавлении задачи](https://yandex.kz/routing/doc/kk/vrp/add-task.md) была включена опция `detailed_drop_reasons`. {% cut "Пример ответа с детальной информацией" %} ```json "dropped_locations": [ { "detailed_drop_reason": [ { "reason": "Order dropped because of `hard_time_window` violation", // Причина нераспределения. "vehicles": [ // Список идентификаторов автомобилей, которые не смогли выполнить заказ по этой причине. "2" ], "vehicles_count": 1 // Количество этих автомобилей. }, { "reason": "Tags of orders and vehicles are incompatible", "vehicles": [ "1" ], "vehicles_count": 1 } ], }, ], ``` {% endcut %} ### Маршрут {#route} Запланированные маршруты можно посмотреть в массиве `routes` объекта `result`. Последовательность выполнения заказов указана в массиве `route`. Для каждой точки на маршруте можно посмотреть затраченное на поездку до точки время в поле `transit_duration_s` и расстояние до точки `transit_distance_m`. Плановое время прибытия и отправления с каждого заказа можно посмотреть в полях `arrival_time_s` и `departure_time_s` соответственно. Фактическое время — в полях `actual_arrival_time_s` и `actual_departure_time_s` (используется для [допланирования](https://yandex.kz/routing/doc/kk/vrp/additional-planning.md)). Время отображается в формате количества секунд от начала суток планирования. Если в решении есть мультизаказы, то у первого заказа параметр `multi_order` равен `false`, у последующих — `true`. Если после приезда на заказ возникло ожидание, его длительность содержится в поле `waiting_duration_s`. ## Визуализация результата {#map} Вы можете посмотреть решение на карте [mvrp-map](https://yandex.kz/routing/doc/kk/vrp/interface-mvrp-map.md). ## Срок хранения данных {#data-retention-period} Данные по спланированным маршрутам хранятся на серверах Яндекса 1 год от даты решения задачи. Их можно получить с помощью метода [mvrp/fetch-result/{id}](https://yandex.ru/routing/doc/ru/vrp/redoc/index.html#operation/getMVRPTaskResult). При использовании устаревшего метода [/result/mvrp/{id}](https://yandex.ru/routing/doc/ru/vrp/redoc/index.html#operation/getMVRPTaskResultDeprecated) данные будут доступны только за последние 3 месяца. После окончания срока хранения данные могут быть удалены без возможности восстановления. Написать в службу поддержки