Processar dados de viagem

Quando você recupera os dados da viagem, o back-end recebe payloads JSON com detalhes sobre 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 de viagem aos 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 trajeto do motorista, a distância percorrida e o horário previsto de chegada (ETA). Como essas atualizações refletem a rota ativa e em tempo real do motorista, elas podem ser diferentes das rotas pré-calculadas pelo seu back-end (consulte as perguntas frequentes).

O exemplo de código a seguir mostra um payload de dados de viagem quando um motorista inicia a navegação de uma viagem de King's Cross até 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 um início bem-sucedido e monitorar o progresso, avalie o campo state 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 se a viagem foi autenticada e iniciada corretamente.

Processar paradas adicionadas

Os motoristas podem adicionar paradas ao trajeto durante a navegação. Se sim, o Navigation Connect define o campo execution.stopAddedInRoute como true no payload de dados JSON. A API Navigation Connect continua rastreando 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 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 para ele iniciar uma nova sessão de navegação em vez de adicionar a parada à rota atual.

Não é necessário ajustar as entradas de back-end para oferecer suporte a esse recurso.

Resolver problemas de autenticação e inicialização

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 tempo de expiração do token na sua 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 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 nem o Apple CarPlay.
  • O motorista tem uma conexão de Internet ativa.

Processar os dados restantes da rota (somente no Waze)

Se você ativou o relatório do restante do trajeto durante a criação da viagem, seu back-end recebe a polilinha do restante do trajeto e as condições de trânsito em tempo real do local atual do motorista até o destino final.

É possível ingerir e processar esses dados para ativar vários recursos nos seus aplicativos, incluindo os seguintes exemplos:

  • Ativar mapas de rastreamento em tempo real: renderize a polilinha restante da rota em um mapa da Web ou para dispositivos móveis voltado ao cliente para oferecer visibilidade da jornada do motorista.
  • Melhorar a precisão da ETA: combine a polilinha ajustada à via e as velocidades dos intervalos de tráfego para melhorar a logística interna ou as previsões de chegada da entrega.
  • Analisar a conformidade de roteamento: compare a geometria da rota restante com os trajetos de despacho esperados para avaliar a adesão do motorista. Consulte as perguntas frequentes para saber por que as rotas em tempo real e pré-calculadas podem ser diferentes.

O Navigation Connect retorna os detalhes restantes da rota no campo execution.remainingRoute, seja enviando uma solicitação GetTrip ou recebendo atualizações orientadas por 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 da resposta para a 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 categorias de tráfego para os índices de polilinha usando os seguintes valores:

Atualizações do Google Cloud Pub/Sub

Ao recuperar dados de viagem com o Pub/Sub, as atualizações sempre retornam os dados restantes da rota em um FeatureCollection GeoJSON 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.

Conferir 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 restantes da rota 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 do back-end e os custos de uso.

Para otimizar o 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.

Lidar com desvios de rota (somente no Waze)

Se você ativou os relatórios de desvio de rota durante a criação da viagem, quando um motorista sai da rota, a API retorna metadados de desvio de rota. Você pode acessar esses dados das seguintes maneiras:

  • Sob demanda: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_trip em até 5 segundos após a detecção.

Ler a carga útil 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 tomou uma ação inesperada ou seguiu a orientação do sistema:
  • DRIVER_INITIATED_REROUTE: o motorista fez uma escolha ativa (por exemplo, fez uma curva errada ou selecionou manualmente um novo trajeto).
  • SYSTEM_INITIATED_REROUTE: o app de navegação calculou um novo trajeto (por exemplo, devido a mudanças nas condições de trânsito ou interdições de vias).
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 seu app.

Status Descrição Ação recomendada
ARRIVED O motorista chegou ao destino. Confira o remainingDistanceMeters. Se o motorista estacionou 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 automaticamente os motoristas ao seu app quando eles saem de uma sessão antes do tempo, o motorista precisa tocar manualmente no botão de retorno. 		Para ajudar os motoristas a concluir a viagem, 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 acontece 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:
  • O motorista revoga o consentimento.
  • O motorista usa uma plataforma não compatível, como Android Auto ou Apple CarPlay.
  • O app reutiliza um token de viagem em viagens separadas. Por exemplo, o Navigation Connect rejeita solicitações que mudam o destino de uma viagem ou atualizam uma viagem concluída.
  • O motorista está nos Estados Unidos em algum momento durante a viagem, mas o compartilhamento de dados pessoais não está ativado no seu app nesse país quando você verificou o app durante a configuração.
 Volte ao rastreamento manual de status no seu app.