Когда вы получаете данные о поездке , ваша серверная часть получает JSON-данные, подробно описывающие ход поездки водителя. Анализируя эти данные, вы можете отслеживать поездку, обновлять информацию в диспетчерских системах и интерпретировать текущие статусы поездки, чтобы определить следующий шаг для водителя по мере его продвижения или по завершении поездки.
Прочитайте данные из полезной нагрузки.
Google Maps или Waze отправляют данные о поездке на серверы Navigation Connect, когда водитель начинает навигацию, периодически по маршруту (по умолчанию каждые 60 секунд) и по прибытии в пункт назначения. Каждое сообщение в формате JSON содержит соответствующие данные о поездке, включая координаты дороги, пройденное расстояние и расчетное время прибытия (ETA). Поскольку эти обновления отражают активный маршрут водителя в режиме реального времени, они могут отличаться от маршрутов, предварительно рассчитанных вашей системой (см. FAQ ).
Приведенный ниже пример кода демонстрирует данные о поездке, которые водитель получает при запуске навигации для поездки из Кингс-Кросс в Центральный Сент-Джайлс.
{
"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
}
}
Отслеживание статуса активных поездок
Для подтверждения успешного запуска и отслеживания прогресса проверяйте поле статуса в каждом полезном грузе.
| Статус | Описание |
|---|---|
NEW | Маршрут создан, но водитель еще не начал движение. |
ENROUTE | Водитель активно прокладывает маршрут к месту назначения. Используйте этот статус, чтобы подтвердить, что поездка прошла аутентификацию и успешно началась. |
Добавлены остановки для обработки ручек
Водители могут добавлять остановки к своему маршруту во время навигации. В этом случае Navigation Connect устанавливает поле execution.stopAddedInRoute в true в полезной нагрузке данных JSON. API Navigation Connect продолжает отслеживать водителя до исходного пункта назначения. Такие показатели, как расчетное время прибытия (ETA), расстояние и продолжительность поездки, увеличиваются с учетом добавленных остановок.
Способ добавления остановок зависит от навигационного приложения и соответствует его стандартной функциональности:
- Google Maps: Водители могут добавить несколько остановок к своему маршруту.
- Waze: Водители могут добавить только одну остановку. Если водитель попытается добавить еще одну остановку, Waze предложит ему начать новую сессию навигации вместо добавления остановки к текущему маршруту.
Для поддержки этой функции вам не нужно настраивать параметры ввода в бэкэнде.
Устранение неполадок с аутентификацией и запуском.
Если вы не получили статус ENROUTE , вероятно, произошла ошибка аутентификации. Распространенные причины включают неправильно написанные параметры API или истекший срок действия токена поездки. Проверьте время истечения срока действия токена в вашем первоначальном ответе CreateTrip .
Если статус не меняется с NEW на ENROUTE , возможно, устройство водителя препятствует аутентификации. В таких случаях Navigation Connect не отправляет сообщения об ошибках. Проверьте следующее:
- У водителя установлена версия Waze 5.15.5 или выше, либо версия Google Maps 26.14 или выше.
- Водитель не использует Android Auto или Apple CarPlay.
- У водителя есть активное интернет-соединение.
Обработка оставшихся данных маршрута (только для Waze)
Если вы включили отображение оставшегося маршрута при создании поездки , ваша серверная часть получает полилинию оставшегося маршрута и информацию о дорожной ситуации в реальном времени от текущего местоположения водителя до конечного пункта назначения.
Вы можете собирать и обрабатывать эти данные для обеспечения работы различных функций ваших приложений, включая следующие примеры:
- Отображение оставшейся части маршрута на карте в режиме реального времени : отображение полилинии маршрута на веб- или мобильной карте, доступной для клиентов, для обеспечения наглядности поездки водителя.
- Повышение точности расчета времени прибытия : объедините данные о привязке к дороге и скорости движения в определенные интервалы времени, чтобы улучшить внутреннюю логистику или прогнозирование времени прибытия груза.
- Анализ соответствия маршруту : сравните оставшуюся геометрию маршрута с ожидаемыми маршрутами отправки, чтобы оценить соблюдение водителями требований (подробнее о том, почему маршруты в реальном времени и предварительно рассчитанные маршруты могут отличаться, см. в разделе часто задаваемых вопросов ).
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 обновления всегда возвращают оставшиеся данные о маршруте в виде единой FeatureCollection GeoJSON в поле execution.remainingRoute .
Этот формат напрямую объединяет геометрию полилиний с данными о скорости движения транспорта, устраняя необходимость в ручном сопоставлении индексов.
См. пример полезной нагрузки Pub/Sub.
Приведенный ниже пример кода демонстрирует структуру GeoJSON, возвращаемую в поле execution.remainingRoute объекта updatedTrip сообщения Pub/Sub:
{ "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" } } ] }
Оптимизация размера полезной нагрузки
Поскольку массивы координат имеют большой размер, включение оставшихся данных маршрута в сообщения Pub/Sub может значительно увеличить размер полезной нагрузки (до 13–14 КБ на сообщение). При частом обновлении данных этот объем может увеличить нагрузку на серверную часть и затраты на использование ресурсов.
Для оптимизации потока используйте параметр pubsubFieldMask в объекте TripConfig при создании поездки, чтобы исключить поля с большим объемом текста. Подробнее см. раздел «Дополнительные настройки» .
Обработка отклонений от маршрута (только в Waze)
Если вы включили отчеты об отклонениях от маршрута при создании поездки , то при отклонении водителя от маршрута API возвращает метаданные об отклонениях от маршрута. Доступ к этим данным можно получить следующими способами:
- По запросу: вызовите метод
GetTrip. Сервер сохраняет последнее известное состояние отклонения. - В режиме реального времени: Подпишитесь на Google Cloud Pub/Sub. Сервис публикует обновления об отклонениях, используя существующее событие
updated_trip, в течение 5 секунд после обнаружения.
Прочитайте данные о погрешности.
Объект last_route_deviation предоставляет следующие метаданные, которые помогут вам проанализировать событие.
| Поле | Тип | Описание |
|---|---|---|
location | LatLng | Координаты широты и долготы, по которым клиентское устройство зафиксировало отклонение. |
source | TriggerSource | Причина отклонения. Используйте эту информацию, чтобы определить, предпринял ли водитель неожиданные действия или следовал указаниям системы:
|
client_timestamp | Timestamp | Время, когда клиентское устройство обнаружило отклонение. |
server_timestamp | Timestamp | Время обработки сервером обновления данных об отклонении. |
Обработка конечных состояний поездки
Когда водитель достигает пункта назначения или прекращает навигацию, полезная нагрузка возвращает одно из следующих конечных состояний. Используйте эти статусы для запуска соответствующих следующих шагов в вашем приложении.
| Статус | Описание | Рекомендуемые действия |
|---|---|---|
ARRIVED | Водитель добрался до места назначения. | Проверьте remainingDistanceMeters . Если водитель припарковался неподалеку, но не по указанным координатам, рассмотрите возможность добавления пешеходного маршрута в ваше приложение. |
SUSPENDED | Водитель вручную вышел из режима пошаговой навигации до прибытия в пункт назначения. Поскольку Google Maps или Waze не возвращают водителей автоматически в ваше приложение, если они преждевременно завершают сессию, водителю приходится вручную нажимать кнопку возврата. | Чтобы помочь водителям завершить поездку, сравните execution.location с пунктом назначения. Если расстояние еще не достигнуто, предоставьте кнопку или ссылку для возобновления поездки или переключения в пешеходный режим. |
FAILED | Из-за технической ошибки соединение прервалось. Это происходит, если приложение не может рассчитать маршрут или появляется предупреждение о безопасности. Водитель может продолжать движение, но вы не будете получать обновления. | Вернитесь к ручному отслеживанию статуса в вашем приложении. |
CLIENT_ERROR | Этот статус появляется по одной из следующих причин:
| Вернитесь к ручному отслеживанию статуса в вашем приложении. |