Ao recuperar 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 enviam os payloads de dados da viagem para os servidores do Navigation Connect quando o motorista começa 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, a distância percorrida e o horário previsto de chegada (HEC).
O exemplo de código a seguir mostra um payload de dados de viagem para quando um motorista começa 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 os status de viagens ativas
Para confirmar um início bem-sucedido e monitorar o progresso, avalie o campo de status em cada payload.
| Status | Descrição |
|---|---|
NEW |
A viagem é criada, mas o motorista ainda não começou 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 isso acontecer, o Navigation Connect vai definir o campo execution.stopAddedInRoute como true no payload de dados JSON. A API Navigation Connect continua rastreando o motorista em direção ao destino original. As métricas, como o horário previsto de chegada (HEC), a distância e a duração, aumentam para incluir as paradas adicionadas.
O comportamento para adicionar paradas depende do app de navegação e corresponde à funcionalidade padrão dele:
- 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 pedir 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 oferecer suporte a esse recurso.
Resolver problemas de autenticação e início
Se você não receber um status ENROUTE, provavelmente ocorreu 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 horário de expiração do token na resposta CreateTrip inicial.
Se o status não mudar de NEW para ENROUTE, o dispositivo do motorista poderá estar impedindo a autenticação. O Navigation Connect não envia mensagens de erro para esses casos. Confirme o seguinte:
- O motorista tem a versão 5.15.5 ou mais recente do Waze ou a versão 26.14 ou mais recente do Google Maps instalada.
- O motorista não está usando o Android Auto ou o Apple CarPlay.
- O motorista tem uma conexão de Internet ativa.
Processar os dados restantes do trajeto (somente Waze)
Se você ativou a geração de relatórios de trajetos restantes durante a criação da viagem, seu back-end vai receber a polilinha do trajeto ativo e as condições de trânsito em tempo real do local atual do motorista até o destino final.
Você pode ingerir e processar esses dados para ativar vários recursos nos seus aplicativos, incluindo os exemplos a seguir:
- Ativar mapas de rastreamento ao vivo: renderize a polilinha do trajeto restante em um mapa da Web ou para dispositivos móveis voltado ao cliente para oferecer visibilidade da jornada do motorista.
- Melhorar a precisão do HEC: combine a polilinha e as velocidades do intervalo de trânsito para melhorar a logística interna ou as previsões de chegada da entrega.
- Analisar a conformidade de roteamento: compare a geometria do trajeto restante com os trajetos de despacho esperados para avaliar a adesão do motorista.
O Navigation Connect retorna os detalhes do trajeto restante no campo execution.remainingRoute, seja enviando uma solicitação GetTrip ou recebendo atualizações orientadas a 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
Ao chamar 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 polilinha.
Para todos os formatos de polilinha, o Navigation Connect retorna o trânsito como uma lista separada de objetos SpeedReadingInterval no campo execution.remainingRoute.trafficInformation. Esses objetos mapeiam as categorias de trânsito para os índices de polilinha usando os seguintes valores:
startPolylinePointIndex: o índice inicial do intervalo de trânsito na polilinha.endPolylinePointIndex: o índice final do intervalo de trânsito.speed: a categoria de trânsito para esse segmento:NORMAL,SLOWouTRAFFIC_JAM.
Atualizações do Google Cloud Pub/Sub
Ao recuperar dados de viagens com o Pub/Sub,
as atualizações sempre retornam dados de trajetos restantes em um GeoJSON unificado
FeatureCollection no campo execution.remainingRoute.
Esse formato combina a geometria da polilinha com as velocidades de 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 no 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 dados de trajetos 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 da viagem para excluir campos pesados. Para
mais detalhes, consulte Configurações opcionais.
Processar estados de fim de viagem
Quando um motorista chega ao destino ou para a navegação, o payload retorna um dos seguintes estados finais. Use esses status para acionar as próximas etapas adequadas no seu app.
| Status | Descrição | Ação recomendada |
|---|---|---|
ARRIVED |
O motorista chegou ao destino. | Verifique o remainingDistanceMeters. Se o motorista estacionou
por perto, mas não nas coordenadas exatas, considere fornecer instruções 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 automaticamente os motoristas ao seu app quando eles saem de uma sessão mais cedo, o motorista precisa tocar manualmente no botão de retorno. |
Para ajudar os motoristas a concluir a jornada, compare
execution.location com o destino. Se a distância
permanecer, 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 conseguir calcular um trajeto ou se um aviso de segurança aparecer. O motorista ainda pode estar navegando, mas você não vai receber atualizações. | Volte ao rastreamento manual de status no seu app. |
CLIENT_ERROR |
Esse status aparece por um dos seguintes motivos:
|
Volte ao rastreamento manual de status no seu app. |