Planifica una ruta

Nota: Las actualizaciones de la forma en que el SDK de Navigation sigue las rutas planificadas, incluido el nuevo campo betterRouteTimeTolerance, se lanzarán de forma gradual y estarán disponibles para todos los proyectos antes del 22 de octubre de 2026. Hasta entonces, la API de Routes podría rechazar las solicitudes que incluyan betterRouteTimeTolerance.

En ocasiones, es posible que quieras planificar la ruta que tu app proporciona a los usuarios. Usar un token de ruta de la API de Routes, la API de Routes Preferred o la API de Route Optimization puede ayudarte a especificar dos aspectos de la ruta planificada:

• Una polilínea para la ruta

• Tus objetivos de ruta

Por ejemplo, estos son algunos ejemplos de objetivos de enrutamiento que podrías tener:

• Minimizar el tiempo de entrega: Es posible que una empresa que entrega comida quiera minimizar el tiempo que tarda en entregarla.

• Minimizar la duración del viaje o el consumo de combustible: Es posible que una empresa de logística quiera mejorar la eficiencia de sus conductores y reducir los costos de combustible.

• Minimizar el tiempo hasta el destino: Es posible que una operación de despacho de servicios quiera minimizar el tiempo que tardan los operadores en llegar a una solicitud de trabajo.

• Reducir los costos y mejorar la seguridad: Es posible que una empresa de viajes compartidos quiera encontrar una ruta que cueste menos para los pasajeros y evite ciertas áreas por motivos de seguridad.

Importante: La ruta que recorren los conductores puede diferir de la ruta planificada. Los cambios en el tráfico o las condiciones de la ruta, el vehículo que sale de la ruta planificada o el cambio a una ruta más rápida pueden modificar la ruta durante el viaje. Cada vez que el SDK de Navigation calcula una ruta nueva, usa las opciones de ruta de acceso establecidas en tu token de ruta, como evitar peajes.

Para obtener más información sobre cómo planificar una ruta con un token de ruta, consulta Obtén un token de ruta en la API de Routes y Transición de polilíneas y tokens de ruta en la API de Route Optimization.

Por qué usar un token de ruta para los objetivos de ruta

Con un token de ruta de la API de Routes, la API de Routes Preferred o la API de Route Optimization, tienes más control sobre la ruta proporcionada:

• Planifica una ruta con anticipación para que la use el SDK de Navigation.

• Elige la mejor ruta para que la use el SDK de Navigation. Si solicitas tokens de ruta cuando generas rutas en la API de Routes, obtendrás un token de ruta para cada ruta generada. Luego, puedes elegir el token de la ruta que quieras usar cuando lo pases al SDK de Navigation.

• Estima el precio por adelantado, incluidas las estimaciones de la hora estimada de llegada y la distancia. Si bien el costo y el tiempo reales pueden variar, esta estimación reduce la brecha entre el costo esperado y el real de la ruta.

• Especificar objetivos de ruta más avanzados, como la ruta ecológica o la más corta

Nota: Un token de ruta es para un origen y un destino específicos, y para un momento determinado. Debes realizar una nueva solicitud a la API de Routes, la API de Routes Preferred o la API de Route Optimization para obtener un nuevo token de ruta.

Cómo funcionan los tokens de ruta

Puedes usar la API de Routes, la API de Routes Preferred o la API de Route Optimization para planificar una ruta con objetivos de ruta. Puedes pasar un token de ruta que se devuelva desde cualquiera de estas APIs al SDK de Navigation para guiar la forma en que se traza la ruta de tu vehículo.

Esto es lo que sucede cuando solicitas y usas un token de ruta:

1. La API de Routes, la API de Routes Preferred o la API de Route Optimization devuelven un token de ruta encriptado que incluye la polilínea y los objetivos de la ruta.

2. Pasas el token de ruta al SDK de Navigation.

3. El SDK de Navigation inicia la navegación en la ruta planificada, incluso si hay una ruta más rápida disponible.

4. Durante el viaje, si cambian las condiciones del tráfico o de la ruta, o si el vehículo se sale de la ruta planificada, el SDK de Navigation calcula una ruta nueva que sigue los objetivos de la ruta y las opciones de enrutamiento establecidas en tu token de ruta.

Este proceso maximiza la cercanía de la ruta real a la ruta planificada.

Por qué es posible que no se siga exactamente una ruta planificada

La navegación comienza en la ruta planificada, pero la ruta real puede diferir de ella en situaciones como las siguientes:

• El vehículo comienza lejos del punto de partida planificado.
• Las condiciones del tráfico o de la ruta cambian durante el viaje.
• El vehículo se desvía de la ruta planificada.

Estas diferencias pueden afectar la distancia, la hora estimada de llegada y otras cualidades importantes del viaje que planificaste.

Sugerencia: Como práctica recomendada, solicita siempre un token de ruta nuevo cada vez que establezcas el destino en el SDK de Navigation y planifica algunas variaciones para evitar cualquier impacto en tu empresa.

Planifica una ruta con un token de ruta

Para planificar una ruta, crea un token de ruta y, luego, pásalo al SDK de Navigation, como se describe en los siguientes pasos:

Paso 1: Crea un token de ruta con la API de Routes, la API de Routes Preferred o la API de Route Optimization

1. Solicita un token de ruta con uno de los siguientes métodos:

   • API de Routes: computeRoutes. Para obtener más información sobre cómo solicitar un token de ruta en la API de Routes, consulta Cómo calcular una ruta y Cómo obtener un token de ruta.

   • API de Routes Preferred: computeCustomRoutes. Para obtener más información sobre cómo solicitar un token de ruta en la API de Routes Preferred, consulta Planifica una ruta.

   • API de Route Optimization: optimizeTours o batchOptimizeTours. Para obtener más información sobre cómo solicitar un token de ruta en la API de Route Optimization, consulta Polilíneas de transición y tokens de ruta.

2. Configura tu solicitud a la API de Routes o a la API de Routes Preferred para cumplir con los requisitos de uso de un token de ruta:

   • Establece travelMode en DRIVE o TWO_WHEELER.
   • Establece routingPreference en TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL.
   • No uses puntos de referencia Via.

Nota: Puedes especificar valores precisos de origen y destino, como entradas, muelles de carga o áreas de retiro designadas, en tu token de ruta con un token de punto de navegación.

Paso 2: Pasa el token de ruta al SDK de Navigation

1. Almacena el token de ruta: En el SDK de Navigation, configura una cadena para almacenar el token de ruta. Por ejemplo:

   let routeToken = "route token returned by Routes API"
   

   Ejemplo de un token de ruta devuelto:

   {
   // Other fields
   "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
   }
   

2. Pasa el token de ruta al SDK de Navigation con mapView.navigator.setDestinations. Especifica los mismos puntos de referencia de destino que usaste cuando creaste el token de ruta:

   mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})
   

   Nota: Si necesitas volver a recorrer la misma ruta, solicita un nuevo token de ruta.

   El método setDestinations pasa el estado de la solicitud a su devolución de llamada. Si encuentra una ruta desde la ubicación del usuario hasta el destino proporcionado, el estado es .OK (GMSRouteStatusOK).

Situaciones con varias paradas

Puedes configurar un máximo de 25 puntos de referencia.

El método setDestinations no admite viajes con varias paradas. Usa continueToNextDestinationWithCompletion() para avanzar el punto de referencia al siguiente tramo del viaje.

Precaución: En ocasiones, llamar al método continueToNextDestinationWithCompletion() puede generar un evento de llegada incorrecto, en el que el destino que se acaba de completar parece volver a seleccionarse.

Ejemplo

En los siguientes ejemplos de código, se muestra cómo recuperar una ruta planificada.

Swift

let location = CLLocationCoordinate2D(latitude: 47.67, longitude: -122.20)
let waypoint1 = GMSNavigationWaypoint(location: location, title: "waypoint from location")!
let waypoint2 = GMSNavigationWaypoint(placeID: "samplePlaceID", title: "waypoint from Place ID")!

let routeToken = "route token returned by Routes API"
mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})

Objective-C

CLLocationCoordinate2D location = CLLocationCoordinate2DMake(47.67, -122.20);
GMSNavigationWaypoint *waypoint1 = [[GMSNavigationWaypoint alloc] initWithLocation:location title:@"waypoint from location"];
GMSNavigationWaypoint *waypoint2 = [[GMSNavigationWaypoint alloc] initWithPlaceID:@"samplePlaceID"
                                                                            title:@"waypoint from Place ID"];
NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinations:@[waypoint1, waypoint2]
                        routeToken:routeToken
                          callback:^(GMSRouteStatus routeStatus){...}];

Cómo interactúan los tokens de ruta y el SDK de Navigation

A continuación, se muestra cómo el SDK de Navigation controla la ruta planificada:

• Anula los destinos establecidos anteriormente.

• Usa la ubicación de partida del vehículo.

• Se ajusta según las condiciones de la ruta y el tráfico. Consulta Por qué es posible que no se siga exactamente una ruta planificada.

• Usa las opciones de ruta de acceso establecidas en tu token de ruta en lugar de los siguientes parámetros de configuración de tu app, incluso cuando calcula una ruta nueva durante el viaje:

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction
  • El modo de viaje establecido en tu app

• Sigue estos parámetros de configuración cuando calcula o ajusta la ruta:

  • Objetivos de ruta de tu token de ruta, como la ruta ecológica o la ruta más corta. Si el SDK de Navigation tiene que ajustar la ruta, usa los objetivos de ruta que especificaste cuando solicitaste el token de ruta.

  • Opciones relacionadas con los puntos de referencia de tu app, como la preferencia de lado de la ruta. Usa las mismas opciones relacionadas con los puntos de referencia que especificaste cuando solicitaste el token de ruta.