Planifica una ruta

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 o la API de Route Optimization puede ayudarte a especificar dos cosas para tu 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 sus 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 las condiciones del tráfico o 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 o de 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.

• Especifica 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 en un momento determinado. Debes realizar una nueva solicitud a la API de Routes o a la API de Route Optimization para obtener un token de ruta nuevo.

Cómo funcionan los tokens de ruta

Puedes usar la API de Routes 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 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 y las opciones de ruta establecidos 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 sale 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 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 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 para que cumpla con los requisitos para usar 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 de 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 el método setDestinationsWithToken:completionHandler: de mapView.navigator. El SDK de Navigation obtiene los destinos y las opciones de ruta del token de ruta, por lo que no es necesario que pases puntos de referencia.

   La modalidad de viaje establecida en tu app, como mapView.travelMode, debe ser uno de los siguientes valores:

   • .driving (GMSNavigationTravelModeDriving): Conducción. Este es el valor predeterminado, por lo que la mayoría de las apps no necesitan cambiarlo.
   • .twoWheeler (GMSNavigationTravelModeTwoWheeler): Vehículo de dos ruedas.

   Cualquier otro medio de transporte hace que la solicitud falle con .travelModeUnsupported (GMSRouteStatusTravelModeUnsupported). Con cualquiera de los valores admitidos, la ruta usa el medio de transporte de tu token de ruta. Por ejemplo, si tu app usa la conducción y tu token de ruta es para una ruta de vehículo de dos ruedas, el SDK de Navigation proporciona una ruta de vehículo de dos ruedas. Para confirmar qué modo de viaje usa la ruta, consulta resolvedParameters.travelMode. Para obtener más información, consulta Opciones de enrutamiento resueltas.

   Nota: Si tu app usa una versión del SDK de Navigation anterior a la 11.3, usa el método setDestinations:routeToken:callback: obsoleto y pasa los mismos puntos de referencia de destino que usaste para crear el token de ruta.

3. Verifica el estado de la ruta en tu controlador de finalización. Cuando el SDK de Navigation termina de calcular la ruta, pasa un objeto GMSNavigationRouteDescription al controlador de finalización. Si encuentra una ruta desde la ubicación del vehículo hasta los destinos en tu token de ruta, el routeStatus de la descripción de la ruta es .OK (GMSRouteStatusOK) y puedes iniciar la guía. De lo contrario, el controlador de finalización también recibe un NSError que describe la falla. Por ejemplo:

   mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
     if routeDescription?.routeStatus == .OK {
       self?.mapView.navigator?.isGuidanceActive = true
     }
   }
   

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

Cómo verificar si el SDK de Navigation aplicó tu token de ruta

Un estado de ruta de .OK significa que el SDK de Navigation encontró una ruta, pero no necesariamente la que planificaste. Para verificar si la ruta coincide con la que planificaste, sigue estos pasos en tu controlador de finalización:

1. Confirma que el routeStatus de la descripción de la ruta sea .OK. El SDK de Navigation proporciona detalles del token de ruta solo cuando encuentra una ruta. Para obtener más información, consulta el paso 2.

2. Obtén el routeTokenExecutionDetails de la descripción de la ruta, un objeto que se ajusta al protocolo GMSNavigationRouteTokenExecutionDetails. Si el servidor no proporciona detalles del token de ruta, esta propiedad es nil.

3. Verifica la propiedad tokenExecutionStatus de los detalles de la ejecución. Si es .tokenSuccessfullyApplied, la ruta coincide con la ruta planificada. Cualquier otro estado significa que la ruta puede diferir de la ruta planificada. Para obtener más información sobre cada estado, consulta Valores de estado de ejecución de tokens.

4. Opcional: Si el estado es .tokenSuccessfullyApplied, verifica la propiedad resolvedParameters de los mismos detalles de ejecución para ver qué opciones de ruta usa, como si evita peajes. Para obtener más información, consulta Opciones de enrutamiento resueltas.

Valores del estado de ejecución del token

Si routeStatus es .OK, puedes iniciar la guía con cualquier estado de ejecución del token. El estado te indica si la ruta sigue la ruta planificada.

Estado	Sigue la ruta planificada.	Descripción
.tokenSuccessfullyApplied	Sí	El SDK de Navigation aplicó tu token de ruta.
.tokenAppliedWithLocationMismatch	No necesariamente.	El SDK de Navigation no pudo volver a crear la ruta planificada y el dispositivo estaba a más de 25 metros del origen en tu token de ruta. La ruta aún usa los destinos y las opciones de enrutamiento de tu token de ruta.
.tokenIgnoredOther	No necesariamente.	El SDK de Navigation no pudo volver a crear la ruta planificada por otro motivo, por ejemplo, porque una ruta de la ruta planificada está cerrada. La ruta aún usa los destinos y las opciones de enrutamiento de tu token de ruta.
.noTokenProvided	No aplicable	La solicitud de ruta no incluyó un token de ruta.
.unknown	Desconocido	El estado es desconocido.

Si la ruta no sigue necesariamente la ruta planificada y la ruta exacta es importante, por ejemplo, porque la usaste para calcular un precio, registra el estado o solicita un nuevo token de ruta desde la ubicación actual del vehículo.

Opciones de enrutamiento resueltas

resolvedParameters es un objeto que cumple con el protocolo GMSNavigationRouteTokenResolvedParameters o nil si las opciones de planificación de ruta no están disponibles. Tiene las siguientes propiedades:

• travelMode: Es la modalidad de viaje que usa la ruta, como .driving (GMSNavigationTravelModeDriving). El SDK de Navigation también informa .driving cuando la ruta usa una modalidad de viaje que no tiene un valor coincidente o cuando la modalidad de viaje no está disponible.
• avoidTolls: Indica si la ruta evita peajes.
• avoidHighways: Indica si la ruta evita autopistas.
• avoidFerries: Indica si la ruta evita los ferris.
• avoidTunnels: Indica si la ruta se calculó para evitar túneles cuando sea posible.
• avoidVignettes: Son los países en los que se calculó la ruta para evitar las viñetas de peaje cuando sea posible, como códigos de región de dos letras de Unicode CLDR, como CH para Suiza.
• rerouteStrategy: Es la estrategia que usa el backend de enrutamiento para calcular rutas nuevas durante el viaje. Las estrategias incluyen .bestBasedOnTokenParameters (GMSNavigationRerouteStrategyBestBasedOnTokenParameters), que usa los parámetros de enrutamiento en tu token de ruta para calcular rutas nuevas.

Si el estado de ejecución del token no es .tokenSuccessfullyApplied, el SDK de Navigation solo informa travelMode, avoidTolls, avoidHighways y avoidFerries. Las otras propiedades tienen sus valores predeterminados, incluso si solicitaste evitar túneles o viñetas de peaje cuando solicitaste el token de ruta: avoidTunnels es false (NO), avoidVignettes está vacío y rerouteStrategy es .unknown (GMSNavigationRerouteStrategyUnknown).

Ejemplo

En el siguiente ejemplo de código, se muestra cómo planificar una ruta con un token de ruta, verificar si el SDK de Navigation aplicó el token y, luego, iniciar la guía.

Swift

let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  // Check whether the Navigation SDK found a route.
  guard routeDescription?.routeStatus == .OK else {
    print("Route error: \(error?.localizedDescription ?? "unknown")")
    return
  }

  // Check whether the Navigation SDK applied the route token.
  if let executionDetails = routeDescription?.routeTokenExecutionDetails {
    if executionDetails.tokenExecutionStatus != .tokenSuccessfullyApplied {
      print("The route might differ from your planned route.")
    }
  } else {
    print("Route token details aren't available.")
  }

  self?.mapView.navigator?.isGuidanceActive = true
}

Objective-C

NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinationsWithToken:routeToken
                          completionHandler:^(id<GMSNavigationRouteDescription> _Nullable routeDescription,
                                              NSError *_Nullable error) {
  // Check whether the Navigation SDK found a route.
  if (routeDescription.routeStatus != GMSRouteStatusOK) {
    NSLog(@"Route error: %@", error.localizedDescription);
    return;
  }

  // Check whether the Navigation SDK applied the route token.
  id<GMSNavigationRouteTokenExecutionDetails> executionDetails =
      routeDescription.routeTokenExecutionDetails;
  if (executionDetails == nil) {
    NSLog(@"Route token details aren't available.");
  } else if (executionDetails.tokenExecutionStatus !=
             GMSNavigationRouteTokenExecutionStatusTokenSuccessfullyApplied) {
    NSLog(@"The route might differ from your planned route.");
  }

  mapView.navigator.guidanceActive = YES;
}];

Situaciones con varias paradas

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

El SDK de Navigation no avanza automáticamente al siguiente destino. Cuando el vehículo llegue a un punto de referencia, llama a continueToNextDestinationWithCompletion: para iniciar el siguiente tramo del viaje. Esto también se aplica a los tokens de ruta que tienen puntos de referencia intermedios. Cuando avanzas al siguiente destino, el SDK de Navigation sigue la ruta de tu token de ruta en lugar de planificar una nueva.

Advertencia: 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.

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 token de ruta, como la preferencia de lado de la ruta.

Nota: Con setDestinationsWithToken:completionHandler:, no pasas puntos de referencia, por lo que el SDK de Navigation usa los destinos y las opciones de puntos de referencia de tu token de ruta. Para establecer opciones de puntos de referencia, como la preferencia de lado de la ruta o las paradas del vehículo, usa los campos sideOfRoad y vehicleStopover en los puntos de referencia de tu solicitud a la API de Routes. El origen siempre es la ubicación del dispositivo, por lo que no se aplican las opciones que configures en el origen en tu solicitud a la API de Routes.