Cómo controlar los datos de viajes

Cuando recuperas los datos de tu viaje, tu backend recibe cargas útiles de JSON que detallan el progreso del viaje del conductor. Analiza estos datos para supervisar el viaje, actualizar tus sistemas de despacho e interpretar los estados actuales del viaje para determinar el siguiente paso del conductor a medida que avanza o cuando finaliza un viaje.

Cómo leer la carga útil de datos

Google Maps o Waze envían las cargas útiles de datos de viajes a los servidores de Navigation Connect cuando el conductor comienza a navegar, periódicamente a lo largo de la ruta (cada 60 segundos de forma predeterminada) y cuando el conductor llega al destino. Cada mensaje JSON contiene datos de viaje relevantes, incluidas las coordenadas ajustadas a la ruta del conductor, la distancia recorrida y la hora estimada de llegada (ETA). Dado que estas actualizaciones reflejan la ruta activa en tiempo real del conductor, es posible que difieran de las rutas que calcula previamente tu backend (consulta las preguntas frecuentes).

En el siguiente ejemplo de código, se muestra una carga útil de datos de viaje para cuando un conductor inicia la navegación de un viaje desde King's Cross hasta 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
  }
}

Supervisa los estados de los viajes activos

Para confirmar que el inicio fue exitoso y supervisar el progreso, evalúa el campo state en cada carga útil.

Estado Descripción
NEW Se creó el viaje, pero el conductor aún no comenzó a navegar.
ENROUTE El conductor está navegando activamente hacia el destino. Usa este estado para confirmar que el viaje se autenticó y se inició correctamente.

Cómo controlar las paradas agregadas

Los conductores pueden agregar paradas a su ruta durante la navegación. Si es así, Navigation Connect establece el campo execution.stopAddedInRoute en true en la carga útil de datos JSON. La API de Navigation Connect sigue haciendo un seguimiento del conductor hacia el destino original. Las métricas, como la hora estimada de llegada (ETA), la distancia y la duración, aumentan para incluir las paradas agregadas.

El comportamiento para agregar paradas depende de la app de navegación y coincide con su funcionalidad estándar:

  • Google Maps: Los conductores pueden agregar varias paradas a su ruta.
  • Waze: Los conductores solo pueden agregar una parada. Si un conductor intenta agregar otra parada, Waze le pedirá que inicie una nueva sesión de navegación en lugar de agregar la parada a la ruta actual.

No es necesario que ajustes las entradas de tu backend para admitir esta función.

Soluciona problemas de autenticación y de inicio

Si no recibes un estado de ENROUTE, es probable que se haya producido un error de autenticación. Entre las causas comunes, se incluyen parámetros de API mal escritos o un token de viaje vencido. Verifica la hora de vencimiento del token en tu respuesta inicial de CreateTrip.

Si el estado no cambia de NEW a ENROUTE, es posible que el dispositivo del conductor esté impidiendo la autenticación. Navigation Connect no envía mensajes de error en estos casos. Verifica lo siguiente:

  • El conductor tiene instalada la versión 5.15.5 o una posterior de Waze, o la versión 26.14 o una posterior de Google Maps.
  • El conductor no está usando Android Auto ni Apple CarPlay.
  • El conductor tiene una conexión a Internet activa.

Cómo controlar los datos de ruta restantes (solo en Waze)

Si habilitaste el informe de ruta restante durante la creación del viaje, tu backend recibirá la polilínea de la ruta restante y las condiciones del tráfico en tiempo real desde la ubicación actual del conductor hasta su destino final.

Puedes transferir y procesar estos datos para potenciar varias funciones en tus aplicaciones, incluidos los siguientes ejemplos:

  • Potencia los mapas de seguimiento en vivo: Renderiza la polilínea de la ruta restante en un mapa web o para dispositivos móviles orientado al cliente para brindar visibilidad del viaje del conductor.
  • Mejora la precisión de la ETA: Combina la polilínea ajustada a la ruta y las velocidades de los intervalos de tráfico para mejorar la logística interna o las predicciones de llegada de las entregas.
  • Analiza el cumplimiento de la ruta: Compara la geometría de la ruta restante con las rutas de envío esperadas para evaluar el cumplimiento del conductor (consulta las preguntas frecuentes para obtener detalles sobre por qué las rutas en tiempo real y las precalculadas pueden diferir).

Navigation Connect devuelve los detalles de la ruta restantes en el campo execution.remainingRoute, ya sea que envíes una solicitud de GetTrip o recibas actualizaciones basadas en eventos con Google Cloud Pub/Sub. Sin embargo, la forma en que la carga útil formatea y estructura estos datos depende del método de recuperación que uses.

Método GetTrip

Cuando llamas al método GetTrip, el formato de respuesta de la polilínea depende del parámetro routePolylineFormat que especificaste en tu solicitud. Para obtener más información, consulta Cómo personalizar formatos de polilíneas.

Para todos los formatos de polilíneas, Navigation Connect devuelve el tráfico como una lista separada de objetos SpeedReadingInterval en el campo execution.remainingRoute.trafficInformation. Estos objetos asignan las categorías de tráfico a los índices de polilíneas con los siguientes valores:

Actualizaciones de Google Cloud Pub/Sub

Cuando recuperas datos de viajes con Pub/Sub, las actualizaciones siempre devuelven los datos de ruta restantes en un objeto FeatureCollection unificado de GeoJSON en el campo execution.remainingRoute.

Este formato combina directamente la geometría de la polilínea con las velocidades del tráfico, lo que elimina la necesidad de asignar índices manualmente.

Consulta un ejemplo de carga útil de Pub/Sub

En la siguiente muestra de código, se muestra la estructura de GeoJSON que se devuelve en el campo execution.remainingRoute dentro del objeto updatedTrip de un mensaje de 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"
      }
    }
  ]
}

Optimiza el tamaño de la carga útil

Dado que los arrays de coordenadas son grandes, incluir los datos de ruta restantes en tus mensajes de Pub/Sub puede aumentar significativamente el tamaño de la carga útil (hasta 13 o 14 KB por mensaje). Si recibes actualizaciones de alta frecuencia, este volumen puede aumentar la carga de procesamiento del backend y los costos de uso.

Para optimizar tu transmisión, usa el parámetro pubsubFieldMask en tu objeto TripConfig durante la creación del viaje para excluir los campos pesados. Para obtener más información, consulta Configuraciones opcionales.

Cómo controlar las desviaciones de la ruta (solo en Waze)

Si habilitaste los informes de desviación de ruta durante la creación del viaje, cuando un conductor se desvíe de la ruta, la API devolverá metadatos de desviación de ruta. Puedes acceder a estos datos de las siguientes maneras:

  • A pedido: Llama al método GetTrip. El servidor persiste el último estado de desviación conocido.
  • En tiempo real: Suscríbete a Google Cloud Pub/Sub. El servicio publica actualizaciones de desviación con el evento updated_trip existente en un plazo de 5 segundos después de la detección.

Cómo leer la carga útil de desviación

El objeto last_route_deviation proporciona los siguientes metadatos para ayudarte a analizar el evento.

Campo Tipo Descripción
location LatLng Son las coordenadas de latitud y longitud en las que el dispositivo cliente registró la desviación.
source TriggerSource Es el motivo de la desviación. Úsalo para determinar si el conductor realizó una acción inesperada o siguió la orientación del sistema:
  • DRIVER_INITIATED_REROUTE: El conductor tomó una decisión activa (por ejemplo, girar en una dirección incorrecta o seleccionar manualmente una ruta nueva).
  • SYSTEM_INITIATED_REROUTE: La app de navegación calculó una nueva ruta (por ejemplo, debido a cambios en las condiciones del tráfico o cierres de rutas).
client_timestamp Timestamp Es la fecha y hora en que el dispositivo cliente detectó la desviación.
server_timestamp Timestamp Es la fecha y hora en que el servidor procesó la actualización de la desviación.

Cómo controlar los estados de finalización del viaje

Cuando un conductor llega al destino o deja de navegar, la carga útil devuelve uno de los siguientes estados finales. Usa estos estados para activar los próximos pasos adecuados en tu app.

Estado Descripción Acción recomendada
ARRIVED El conductor llegó al destino. Revisa la remainingDistanceMeters. Si el conductor se estacionó cerca, pero no en las coordenadas exactas, considera proporcionar instrucciones para caminar en tu app.
SUSPENDED El conductor salió manualmente de la navegación paso a paso antes de llegar al destino.
Dado que Google Maps o Waze no regresan automáticamente a los conductores a tu app cuando salen de una sesión antes de tiempo, el conductor debe presionar manualmente el botón de regreso. 		Para ayudar a los conductores a completar su viaje, compara execution.location con el destino. Si aún queda distancia por recorrer, proporciona un botón o un vínculo para reanudar el viaje o cambiar al modo a pie.
FAILED Se interrumpió la conexión debido a un error técnico. Esto ocurre si la app no puede calcular una ruta o aparece una advertencia de seguridad. Es posible que el conductor siga navegando, pero no recibirás actualizaciones. Vuelve al seguimiento manual del estado en tu app.
CLIENT_ERROR Este estado aparece por uno de los siguientes motivos:
  • El conductor revoca el consentimiento.
  • El conductor usa una plataforma no compatible, como Android Auto o Apple CarPlay.
  • Tu app reutiliza un token de viaje en viajes separados. Por ejemplo, Navigation Connect rechaza las solicitudes que cambian el destino de un viaje o actualizan un viaje completado.
  • El conductor se encuentra en Estados Unidos en cualquier momento durante el viaje, pero tu app no tiene habilitado el uso compartido de datos en Estados Unidos cuando verificaste tu app durante la configuración.
 Vuelve al seguimiento manual del estado en tu app.