Когда вы получаете данные о поездке, ваш сервер получает полезную нагрузку JSON с подробными сведениями о ходе поездки. Проанализируйте эти полезные нагрузки, чтобы отслеживать поездку, обновлять диспетчерские системы и интерпретировать текущие статусы поездки, чтобы определить следующий шаг для водителя по мере его продвижения или по завершении поездки.
Как прочитать полезную нагрузку данных
Google Карты или Waze отправляют пакеты данных о поездке на серверы Navigation Connect, когда водитель начинает навигацию, периодически по маршруту (по умолчанию каждые 60 секунд) и когда водитель прибывает в пункт назначения. Каждое сообщение JSON содержит данные о поездке, включая привязанные к дороге координаты водителя, пройденное расстояние и расчетное время прибытия. Поскольку эти обновления отражают активный маршрут водителя в реальном времени, они могут отличаться от маршрутов, предварительно рассчитанных вашим бэкендом (см. Часто задаваемые вопросы).
В примере кода ниже показаны полезные данные о поездке, когда водитель начинает навигацию по маршруту от Кингс-Кросс до Сентрал Сент-Джайлс.
{
"name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
"state": "ENROUTE",
"execution": {
"origin": {
"point": {
"latitude": 51.5333329,
"longitude": -0.1265845
}
},
"destination": {
"point": {
"latitude": 51.515598,
"longitude": -0.1277623
}
},
"location": {
"point": {
"latitude": 51.5333329,
"longitude": -0.1265845
},
"sourceTime": "2025-05-30T12:37:26Z",
"serverTime": "2025-05-30T12:37:26.221069Z"
},
"traveledDuration": "0s",
"remainingDuration": "990s",
"traveledDistanceMeters": 0,
"remainingDistanceMeters": 2879,
"stopAddedInRoute": false
}
}
Как отслеживать статусы активных поездок
Чтобы убедиться, что запуск прошел успешно, и отслеживать ход выполнения, проверяйте поле state в каждой полезной нагрузке.
| Статус | Описание |
|---|---|
NEW |
Поездка создана, но водитель ещё не начал навигацию. |
ENROUTE |
Водитель активно перемещается к пункту назначения. Этот статус подтверждает, что поездка аутентифицирована и успешно начата. |
Обработка добавленных остановок
Водители могут добавлять остановки на маршрут во время навигации. Если да, Navigation Connect задает для поля execution.stopAddedInRoute значение true в полезной нагрузке данных JSON. Navigation Connect API продолжает отслеживать водителя на пути к исходному пункту назначения. Такие показатели, как расчетное время прибытия, расстояние и продолжительность, увеличиваются с учетом добавленных остановок.
Поведение при добавлении остановок зависит от приложения и соответствует его стандартной функциональности:
- Google Карты. Водители могут добавлять в маршрут несколько остановок.
- Waze. Водители могут добавить только одну остановку. Если водитель попытается добавить ещё одну остановку, Waze предложит ему начать новую поездку, а не добавлять остановку в текущий маршрут.
Чтобы использовать эту функцию, вам не нужно менять входные данные на сервере.
Устранение неполадок с аутентификацией и запуском
Если вы не получили статус ENROUTE, скорее всего, произошла ошибка аутентификации. Распространенные причины: опечатки в параметрах API или истекший срок действия токена поездки. Проверьте срок действия токена в исходном ответе CreateTrip.
Если статус не меняется с NEW на ENROUTE, возможно, аутентификация не выполняется из-за устройства водителя. В таких случаях Navigation Connect не отправляет сообщения об ошибках. Проверьте следующее:
- У водителя установлено приложение Waze версии 5.15.5 или более поздней либо Google Карты версии 26.14 или более поздней.
- Водитель не использует Android Auto или Apple CarPlay.
- У водителя есть подключение к интернету.
Обработка оставшихся данных маршрута
Если вы включили отчеты об оставшемся маршруте при создании поездки, ваш бэкенд получает ломаную линию оставшегося маршрута и информацию о загруженности дорог в реальном времени от текущего местоположения водителя до конечного пункта назначения. У водителей должно быть установлено приложение Waze версии 5.20.0.2 или более поздней для Android, 5.20.0.1 или более поздней для iOS или Google Карты версии 26.27 или более поздней для Android.
Вы можете получать и обрабатывать эти данные, чтобы использовать их в своих приложениях, например:
- Карты отслеживания в реальном времени. Отрисовка оставшейся части маршрута на карте в веб-интерфейсе или мобильном приложении, чтобы клиент мог видеть, где находится водитель.
- Повышение точности расчетного времени прибытия. Объедините ломаную линию с привязкой к дороге и интервалы скорости движения, чтобы улучшить внутреннюю логистику или прогнозирование времени доставки.
- Анализ соблюдения маршрута. Сравните геометрию оставшегося маршрута с ожидаемыми маршрутами диспетчера, чтобы оценить соблюдение маршрута водителем (подробности о том, почему маршруты в реальном времени и предварительно рассчитанные маршруты могут отличаться, см. в разделе часто задаваемых вопросов).
Navigation Connect возвращает сведения об оставшейся части маршрута в поле execution.remainingRoute, независимо от того, отправляете ли вы запрос GetTrip или получаете обновления на основе событий с помощью Google Cloud Pub/Sub. Однако формат и структура этих данных в полезной нагрузке зависят от используемого метода получения.
GetTrip способ
При вызове метода GetTrip формат ответа для ломаной линии зависит от параметра routePolylineFormat, указанного в запросе. Подробнее о настройке форматов ломаных линий…
Для всех форматов ломаных линий Navigation Connect возвращает трафик в виде отдельного списка объектов SpeedReadingInterval в поле execution.remainingRoute.trafficInformation. Эти объекты сопоставляют категории трафика с индексами ломаной линии, используя следующие значения:
startPolylinePointIndex– начальный индекс интервала трафика на ломаной линии.endPolylinePointIndex– конечный индекс интервала трафика.speed– категория трафика для этого сегмента:NORMAL,SLOWилиTRAFFIC_JAM.
Обновления Google Cloud Pub/Sub
Когда вы получаете данные о поездке с помощью Pub/Sub, обновления всегда возвращают данные об оставшемся маршруте в унифицированном формате GeoJSON FeatureCollection в поле execution.remainingRoute.
Этот формат напрямую объединяет геометрию ломаной линии со скоростью движения, устраняя необходимость сопоставлять индексы вручную.
Пример полезной нагрузки издателя-подписчика
В примере кода ниже показана структура GeoJSON, возвращаемая в поле execution.remainingRoute объекта updatedTrip сообщения издатель-подписчик.
{ "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [ [-122.3934, 37.7955], [-122.4010, 37.7980] ] }, "properties": { "speed": "SLOW" } }, { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [ [-122.4010, 37.7980], [-122.4058, 37.8025], [-122.4187, 37.8021] ] }, "properties": { "speed": "NORMAL" } } ] }
Оптимизация размера полезной нагрузки
Поскольку массивы координат велики, включение оставшихся данных маршрута в сообщения издатель-подписчик может значительно увеличить размер полезной нагрузки (до 13–14 КБ на сообщение). Если вы получаете обновления с высокой частотой, этот объем может увеличить нагрузку на серверную обработку и расходы на использование.
Чтобы оптимизировать поток, используйте параметр pubsubFieldMask в объекте TripConfig при создании поездки. Это позволит исключить тяжелые поля. Подробнее о дополнительных настройках…
Как обрабатывать отклонения от маршрута (только в Waze)
У водителей должна быть установлена версия Waze 5.22 или более поздняя.
Если вы включили отчеты об отклонении от маршрута при создании поездки, то, когда водитель отклоняется от маршрута, API возвращает метаданные об отклонении от маршрута. Получить доступ к этим данным можно следующими способами:
- По запросу. Вызовите метод
GetTrip. Сервер сохраняет последнее известное состояние отклонения. - В реальном времени. Подпишитесь на Google Cloud Pub/Sub. Сервис публикует обновления об отклонениях, используя существующее событие
updated_trip, в течение пяти секунд после обнаружения.
Прочитайте полезную нагрузку отклонения.
Объект last_route_deviation предоставляет следующие метаданные, которые помогают анализировать событие:
| Поле | Тип | Описание |
|---|---|---|
location |
LatLng |
Координаты широты и долготы, где клиентское устройство зафиксировало отклонение. |
source |
TriggerSource |
Причина отклонения. Используйте это, чтобы определить, совершил ли водитель неожиданное действие или следовал указаниям системы:
|
client_timestamp |
Timestamp |
Время, когда клиентское устройство обнаружило отклонение. |
server_timestamp |
Timestamp |
Время, когда сервер обработал обновление отклонения. |
Обработка состояний завершения поездки
Когда водитель прибывает в пункт назначения или останавливает навигацию, полезная нагрузка возвращает одно из следующих конечных состояний. Используйте эти статусы, чтобы запускать в приложении нужные действия.
| Статус | Описание | Рекомендуемые действия |
|---|---|---|
ARRIVED |
Водитель прибыл в пункт назначения. | Посмотрите remainingDistanceMeters. Если водитель припарковался поблизости, но не в точном месте, укажите в приложении пешеходный маршрут. |
SUSPENDED |
Водитель вручную вышел из режима пошаговой навигации до прибытия в пункт назначения. Поскольку Google Карты и Waze не возвращают водителей в ваше приложение автоматически, когда они выходят из сеанса раньше времени, водитель должен вручную нажать кнопку возврата. |
Чтобы помочь водителям завершить поездку, сравните execution.location с пунктом назначения. Если расстояние до пункта назначения ещё осталось, предоставьте кнопку или ссылку, чтобы возобновить поездку или переключиться в режим ходьбы. |
FAILED |
Подключение прервано из-за технической ошибки. Это происходит, если приложение не может рассчитать маршрут или появляется предупреждение о безопасности. Водитель может продолжать движение по маршруту, но вы не будете получать обновления. | Отслеживайте статус вручную в приложении. |
CLIENT_ERROR |
Этот статус появляется по одной из следующих причин:
|
Отслеживайте статус вручную в приложении. |