Quando você recupera os dados da viagem, seu back-end recebe payloads JSON detalhando o progresso da viagem do motorista. Analise esses payloads para monitorar a viagem, atualizar seus sistemas de despacho e interpretar os status atuais da viagem para determinar a próxima etapa do motorista à medida que ele avança ou quando uma viagem é concluída.
Ler o payload de dados
O Google Maps ou o Waze envia os payloads de dados de viagem para os servidores do Navigation Connect quando o motorista inicia a navegação, periodicamente ao longo do trajeto (a cada 60 segundos por padrão) e quando o motorista chega ao destino. Cada mensagem JSON contém dados relevantes da viagem, incluindo as coordenadas do motorista ajustadas à via, a distância percorrida e o horário previsto de chegada (HPC). Como essas atualizações refletem o trajeto ativo e em tempo real do motorista, elas podem ser diferentes dos trajetos pré-calculados pelo back-end (consulte as perguntas frequentes).
O exemplo de código a seguir mostra um payload de dados de viagem para quando um motorista inicia a navegação de uma viagem de King's Cross para Central St. Giles.
{
"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
}
}
Monitorar status de viagens ativas
Para confirmar se o início foi bem-sucedido e monitorar o progresso, avalie o campo
state em cada
payload.
| Status | Descrição |
|---|---|
NEW |
A viagem foi criada, mas o motorista ainda não iniciou a navegação. |
ENROUTE |
O motorista está navegando ativamente até o destino. Use esse status para confirmar que a viagem foi autenticada e iniciada. |
Processar paradas adicionadas
Os motoristas podem adicionar paradas ao trajeto durante a navegação. Se houver,
o Navigation Connect define o campo
execution.stopAddedInRoute
como true no payload de dados JSON. A API Navigation Connect
continua monitorando o motorista até o destino original. Métricas como
horário previsto de chegada (HEC), distância e duração aumentam
para incluir as paradas adicionadas.
O comportamento para adicionar paradas depende do app de navegação e corresponde à funcionalidade padrão:
- Google Maps: os motoristas podem adicionar várias paradas ao trajeto.
- Waze: os motoristas podem adicionar apenas uma parada. Se um motorista tentar adicionar outra parada, o Waze vai solicitar que ele inicie uma nova sessão de navegação em vez de adicionar a parada ao trajeto atual.
Não é necessário ajustar as entradas de back-end para usar esse recurso.
Resolver problemas de autenticação e inicialização
Se você não receber um status ENROUTE, é provável que tenha ocorrido um erro de autenticação. As causas comuns incluem parâmetros de API com erros de ortografia ou um token de viagem expirado. Verifique o prazo de validade do token na resposta inicial de CreateTrip.
Se o status não mudar de NEW para ENROUTE, o dispositivo do motorista pode estar impedindo a autenticação. O Navigation Connect não envia mensagens de erro
nesses casos. Confirme o seguinte:
- O motorista tem o Waze versão 5.15.5 ou mais recente ou o Google Maps versão 26.14 ou mais recente instalado.
- O motorista não está usando o Android Auto nem o Apple CarPlay.
- O motorista tem uma conexão de Internet ativa.
Processar os dados restantes do trajeto
Se você tiver ativado os relatórios de trajeto restante durante a criação de viagens, seu back-end vai receber a polilinha do trajeto restante e as condições de trânsito em tempo real do local atual do motorista até o destino final. Os motoristas precisam da versão 5.20.0.2 ou mais recente do Waze no Android, 5.20.0.1 ou mais recente no iOS ou da versão 26.27 ou mais recente do Google Maps para Android.
É possível ingerir e processar esses dados para potencializar vários recursos nos seus aplicativos, incluindo os seguintes exemplos:
- Melhorar os mapas de acompanhamento em tempo real: renderize a polilinha do trajeto restante em um mapa da Web ou para dispositivos móveis voltado ao cliente para mostrar a jornada do motorista.
- Melhorar a precisão do HEC: combine a polilinha ajustada à via e as velocidades de intervalo de trânsito para melhorar a logística interna ou as previsões de chegada de entregas.
- Analisar a conformidade do trajeto: compare a geometria do trajeto restante com os trajetos de despacho esperados para avaliar a adesão do motorista. Consulte as perguntas frequentes para saber por que os trajetos em tempo real e pré-calculados podem ser diferentes.
O Navigation Connect retorna os detalhes restantes do trajeto no campo
execution.remainingRoute,
seja enviando uma solicitação GetTrip ou recebendo atualizações baseadas em eventos
usando o Google Cloud Pub/Sub. No entanto, a forma como o payload formata e estrutura esses dados depende do método de recuperação usado.
Método GetTrip
Quando você chama o método GetTrip, o formato de resposta da polilinha depende do parâmetro routePolylineFormat especificado na solicitação. Para mais informações, consulte Personalizar formatos de polilinhas.
Para todos os formatos de polilinhas, o Navigation Connect retorna o trânsito como uma lista separada de objetos SpeedReadingInterval no campo execution.remainingRoute.trafficInformation. Esses objetos mapeiam categorias de trânsito para os índices de polilinhas usando os
seguintes valores:
startPolylinePointIndex: o índice inicial do intervalo de trânsito na polilinha.endPolylinePointIndex: o índice final do intervalo de tráfego.speed: a categoria de tráfego para este segmento:NORMAL,SLOWouTRAFFIC_JAM.
Atualizações do Google Cloud Pub/Sub
Quando você recupera dados de viagem com o Pub/Sub,
as atualizações sempre retornam os dados de rota restantes em um GeoJSON
FeatureCollection unificado
no campo
execution.remainingRoute.
Esse formato combina a geometria da polilinha com as velocidades do trânsito diretamente, eliminando a necessidade de mapear índices manualmente.
Confira um exemplo de payload do Pub/Sub
O exemplo de código a seguir mostra a estrutura GeoJSON retornada no campo execution.remainingRoute dentro do objeto updatedTrip de uma mensagem do 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" } } ] }
Otimizar o tamanho do payload
Como as matrizes de coordenadas são grandes, incluir os dados de rota restantes nas mensagens do Pub/Sub pode aumentar significativamente o tamanho do payload (até 13 a 14 KB por mensagem). Se você receber atualizações de alta frequência, esse volume poderá aumentar a carga de processamento de back-end e os custos de uso.
Para otimizar seu stream, use o parâmetro pubsubFieldMask no objeto TripConfig durante a criação de viagens para excluir campos pesados. Para mais detalhes, consulte Configurações
opcionais.
Gerenciar desvios de rota (somente no Waze)
Os motoristas precisam da versão 5.22 ou mais recente do Waze.
Se você tiver ativado os relatórios de desvio de rota durante a criação da viagem, quando um motorista sair da rota, a API vai retornar metadados de desvio de rota. Você pode acessar esses dados das seguintes maneiras:
- On demand: chame o método
GetTrip. O servidor mantém o último estado de desvio conhecido. - Em tempo real: inscreva-se no Google Cloud Pub/Sub. O serviço publica
atualizações de desvio usando o evento
updated_tripem até 5 segundos após a detecção.
Ler o payload de desvio
O objeto last_route_deviation fornece os seguintes metadados para ajudar você a
analisar o evento.
| Campo | Tipo | Descrição |
|---|---|---|
location |
LatLng |
As coordenadas de latitude e longitude em que o dispositivo cliente registrou o desvio. |
source |
TriggerSource |
O motivo do desvio. Use isso para determinar se o motorista realizou
uma ação inesperada ou seguiu as orientações do sistema:
|
client_timestamp |
Timestamp |
O horário em que o dispositivo cliente detectou o desvio. |
server_timestamp |
Timestamp |
O horário em que o servidor processou a atualização do desvio. |
Processar estados de fim de viagem
Quando um motorista chega ao destino ou para de navegar, o payload retorna um dos seguintes estados finais. Use esses status para acionar as próximas etapas adequadas no app.
| Status | Descrição | Ação recomendada |
|---|---|---|
ARRIVED |
O motorista chegou ao destino. | Confira o remainingDistanceMeters. Se o motorista estacionou
por perto, mas não nas coordenadas exatas, considere fornecer rotas a pé
no seu app. |
SUSPENDED |
O motorista saiu manualmente da navegação guiada antes de chegar
ao destino. Como o Google Maps ou o Waze não retornam os motoristas automaticamente ao seu app quando eles saem de uma sessão antes do tempo, o motorista precisa tocar manualmente no botão de voltar. |
Para ajudar os motoristas a concluir o trajeto, compare
execution.location com o destino. Se ainda houver distância, forneça um botão ou link para retomar a viagem ou mudar para o modo de caminhada. |
FAILED |
Um erro técnico interrompeu a conexão. Isso ocorre se o app não consegue calcular um trajeto ou se um aviso de segurança é exibido. O motorista pode continuar navegando, mas você não vai receber atualizações. | Volte para o rastreamento de status manual no app. |
CLIENT_ERROR |
Esse status aparece por um dos seguintes motivos:
|
Volte para o rastreamento de status manual no app. |