Cuando recuperas los datos de tu viaje, tu backend recibe cargas útiles de JSON que detallan el progreso del viaje del conductor. Analiza estas cargas útiles para supervisar el viaje, actualizar tus sistemas de despacho y, además, interpretar los estados actuales del viaje para determinar el siguiente paso del conductor a medida que avanza o cuando concluye un viaje.
Lee 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 inicia la navegación, de forma periódica 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). Debido a que estas actualizaciones reflejan la ruta activa y en tiempo real del conductor, pueden diferir de las rutas calculadas previamente por tu backend (consulta las Preguntas frecuentes).
En la siguiente muestra de código, se indica 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 un inicio correcto 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 comenzó correctamente. |
Cómo controlar las paradas agregadas
Los conductores pueden agregar paradas a su ruta durante la navegación. Si lo hacen,
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 solicita 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 backend para admitir esta función.
Soluciona problemas de autenticación y de inicio
Si no recibes un estado ENROUTE, es probable que se haya producido un error de autenticación. Entre las causas comunes, se incluyen los parámetros de la API mal escritos o un token de viaje vencido. Verifica el tiempo 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 impida 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 posterior de Waze, o la versión 26.14 o posterior de Google Maps.
- El conductor no usa Android Auto ni Apple CarPlay.
- El conductor tiene una conexión a Internet activa.
Cómo controlar los datos de ruta restantes
Si habilitaste los informes de ruta restante durante la creación del viaje, tu backend recibirá la polilínea de la ruta restante y las condiciones de tráfico en tiempo real desde la ubicación actual del conductor hasta su destino final. Los conductores necesitan la versión 5.20.0.2 o posterior de Waze en Android, la versión 5.20.0.1 o posterior en iOS, o la versión 26.27 o posterior de Google Maps para Android.
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 proporcionar visibilidad del viaje del conductor.
- Mejora la precisión de la hora estimada de llegada: 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 las rutas: Compara la geometría de la ruta restante con las rutas de despacho esperadas para evaluar el cumplimiento del conductor (consulta las Preguntas frecuentes para obtener detalles sobre por qué las rutas en tiempo real y las calculadas previamente pueden diferir).
Navigation Connect devuelve los detalles de la ruta restante en el campo execution.remainingRoute, ya sea que envíes una solicitud GetTrip o recibas actualizaciones controladas por 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 Personaliza los formatos de polilínea.
Para todos los formatos de polilínea, Navigation Connect devuelve el tráfico como una lista independiente de objetos SpeedReadingInterval en el campo execution.remainingRoute.trafficInformation. Estos objetos asignan categorías de tráfico a los índices de polilínea con los siguientes valores:
startPolylinePointIndex: Es el índice de inicio del intervalo de tráfico en la polilínea.endPolylinePointIndex: Es el índice final del intervalo de tráfico.speed: Es la categoría de tráfico de este segmento:NORMAL,SLOWoTRAFFIC_JAM.
Actualizaciones de Google Cloud Pub/Sub
Cuando recuperas datos de viajes con Pub/Sub,
las actualizaciones siempre devuelven los datos de la ruta restante en un GeoJSON unificado
FeatureCollection en el campo
execution.remainingRoute.
Este formato combina la geometría de polilínea con las velocidades del tráfico directamente, lo que elimina la necesidad de asignar índices de forma manual.
Consulta un ejemplo de carga útil de Pub/Sub
En la siguiente muestra de código, se indica 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
Debido a que los arrays de coordenadas son grandes, incluir los datos restantes de la ruta 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 detalles, consulta Parámetros de configuración opcionales.
Cómo controlar los desvíos de la ruta (solo para Waze)
Los conductores necesitan la versión 5.22 o posterior de Waze.
Si habilitaste los informes de desvío de la ruta durante la creación del viaje, cuando un conductor se desvía de la ruta, la API devuelve metadatos de desvío de la ruta. Puedes acceder a estos datos de las siguientes maneras:
- On-demand: Llama al método
GetTrip. El servidor conserva el último estado de desviación conocido. - En tiempo real: Suscríbete a Google Cloud Pub/Sub. El servicio publica
actualizaciones de desviaciones con el evento
updated_tripexistente en un plazo de 5 segundos desde la detección.
Lee 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. Úsala para determinar si el conductor realizó una acción inesperada o siguió las instrucciones del sistema:
|
client_timestamp |
Timestamp |
Es la hora en que el dispositivo cliente detectó la desviación. |
server_timestamp |
Timestamp |
Es la hora en que el servidor procesó la actualización de la desviación. |
Cómo controlar los estados de finalización de un viaje
Cuando un conductor llega al destino o detiene la navegación, 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 sobre cómo llegar
a pie en tu app. |
SUSPENDED |
El conductor salió de forma manual de la navegación paso a paso antes de llegar al destino. Debido a que Google Maps o Waze no devuelven 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 Atrás. |
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 |
Un error técnico interrumpió la conexión. Esto ocurre si la app no puede calcular una ruta o si aparece una advertencia de seguridad. Es posible que el conductor siga navegando, pero no recibirás actualizaciones. | Recurre al seguimiento manual del estado en tu app. |
CLIENT_ERROR |
Este estado aparece por uno de los siguientes motivos:
|
Recurre al seguimiento manual del estado en tu app. |