Genera rutas y horas de llegada estimadas para vehículos grandes

A quién está dirigida esta guía: Lee esta guía si eres desarrollador y creas servicios para la planificación y ejecución de viajes con camiones o vehículos grandes. Los casos de uso pertinentes incluyen el cálculo de las distancias y los tiempos de viaje, el cálculo de las horas de llegada estimadas o la generación de rutas que usará una aplicación de navegación.

Qué abarca esta guía: En esta guía, se explica cómo usar la API de Routes con el enrutamiento de vehículos grandes para solicitar rutas, distancia de viaje, tiempo de viaje previsto y horas de llegada estimadas que tengan en cuenta los atributos específicos de un vehículo grande, como un camión comercial o un autobús de pasajeros.

Para obtener información sobre cómo realizar cálculos a nivel de la flota para vehículos grandes con la API de Route Optimization, consulta la documentación sobre el enrutamiento de camiones de Route Optimization.

Qué aprenderás

Aprenderás a hacer lo siguiente:

  • Crear una solicitud de enrutamiento válida
  • Especificar un perfil de vehículo para tu vehículo del mundo real con dimensiones, peso y otras características
  • Interpretar la respuesta, incluido el token de ruta y las marcas de seguridad de viaje

Requisitos previos

  1. Se debe crear tu proyecto de Google Cloud y habilitar la API de Routes.
  2. Tu proyecto debe estar aprovisionado para el enrutamiento de vehículos grandes. Comunícate con tu representante de Google para completar este paso.

Limitaciones

Antes de comenzar, debes tener en cuenta las siguientes limitaciones y requisitos.

  • Disponibilidad geográfica: El enrutamiento de vehículos grandes solo está disponible en los 48 estados contiguos de Estados Unidos.
  • El enrutamiento de vehículos grandes es una oferta en etapa de versión preliminar. Los conductores no deben depender únicamente de las rutas que muestra esta API para que sean seguras o legales. No se garantiza que las rutas sean adecuadas para el vehículo, y seguirlas puede exponer a los conductores a peligros, como puentes bajos o rutas en las que se prohíben los vehículos grandes.
  • Rutas de mejor esfuerzo. En algunos casos, la API no puede encontrar una ruta que cumpla por completo con las restricciones de viaje. En cambio, muestra una ruta de "mejor esfuerzo" que aún puede atravesar áreas restringidas. La respuesta de la API de Routes marca claramente estas rutas en el campo routeRestrictionsPartiallyIgnored. En estos casos, planifica tu ruta con cuidado, idealmente con otros datos de origen. No uses una ruta marcada como una única fuente de información para la planificación o la navegación.
  • Funciones no compatibles: Si bien estamos trabajando para agregar más funciones a esta oferta, el enrutamiento de vehículos grandes no admite lo siguiente:
    • Precios de peajes para camiones
    • Límites de velocidad
    • Enrutamiento para materiales peligrosos radiactivos
  • Límites de uso: Todas las solicitudes están sujetas a los límites estándar de consultas por segundo (QPS).

Cómo compilar una solicitud de ruta para camiones

Para obtener una ruta para camiones, debes enviar una solicitud HTTPS a un extremo de la API de Routes con parámetros específicos que describan tu vehículo.

Extremos

Puedes usar dos extremos para el enrutamiento de camiones:

  • computeRoutes: Calcula una sola ruta entre un origen y un destino.
  • computeRouteMatrix: Calcula la distancia y la duración de una matriz de orígenes y destinos, pero no muestra una polilínea de ruta.

Parámetros clave de la solicitud

En el cuerpo de la solicitud, debes incluir lo siguiente:

  • travelMode: Establece este valor en TRUCK.
  • routingPreference: Establece este valor en TRAFFIC_AWARE_OPTIMAL.
  • routeModifiers: Este objeto contiene el objeto vehicleInfo en el que defines los atributos de tu vehículo. El objeto vehicleInfo se describe en detalle a continuación.

Cómo especificar un perfil de vehículo

Para enviar una solicitud, debes proporcionar un cuerpo de solicitud con un objeto vehicleInfo que describa tu vehículo. Piensa en esta información como una especificación que coincida con los detalles físicos de tu vehículo del mundo real. El servicio requiere estos detalles para mostrar rutas que tengan en cuenta las restricciones de la ruta según los atributos de tu vehículo.

Mediciones del vehículo

Proporciona el peso del vehículo en kilogramos y las dimensiones del vehículo en milímetros, como se indica en los nombres de los campos. Por ejemplo, la altura total debe proporcionarse en milímetros (totalHeightMm). Dado que las dimensiones de los camiones suelen expresarse en pies o metros, es posible que se requiera una conversión de unidades.

Conversión de unidades imperiales a métricas

Cuando realices la conversión de unidades imperiales, siempre considera las dimensiones específicas de tu vehículo junto con los límites de tamaño estándar de la ruta y el paso inferior. Esto puede ser especialmente importante con valores fraccionarios. Según el tamaño del vehículo real, redondear un valor fraccionario puede generar un enrutamiento demasiado restrictivo para el vehículo.

Por ejemplo:

  • Ancho: Muchos remolques de EE.UU. tienen un ancho de 8 pies y 6 pulgadas, lo que equivale a 2,590.8 mm. Si se redondea a 2,591 mm, se indicaría que el vehículo es mayor que 8 pies y 6 pulgadas, lo que lo clasificaría como un vehículo de gran tamaño en las rutas de EE.UU. Esto generaría una ruta que se calculó según restricciones significativamente diferentes de las deseadas.
  • Altura: Una ruta que pasa por debajo de un puente de 11 pies no sería adecuada para un camión con remolque típico con una altura de 13.5 pies. Sin embargo, los camiones de caja más pequeños de alrededor de 10 pies podrían navegar por el paso inferior. Por lo tanto, es fundamental especificar los atributos del vehículo con precisión.

Un diagrama que ilustra las dimensiones de un camión en comparación con las dimensiones de un paso inferior

A continuación, se muestra un fragmento de código que muestra un objeto vehicleInfo de ejemplo:

"vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }

Campos del objeto vehicleInfo

En la siguiente tabla, se muestran todas las definiciones de vehículos y cargas que puedes enviar con la solicitud.

Campo Descripción Notas o valores
totalHeightMm La altura máxima del vehículo En milímetros, redondeado hacia abajo (consulta Conversión de unidades imperiales a métricas para obtener más detalles sobre el redondeo)
totalWidthMm El ancho máximo del vehículo En milímetros, redondeado hacia abajo
totalLengthMm La longitud total combinada del vehículo y cualquier remolque En milímetros, redondeado hacia abajo
totalWeightKg El peso bruto del vehículo (incluidos los remolques y la carga) En kilogramos, redondeado hacia abajo
totalAxleCount La cantidad total de ejes del vehículo y cualquier remolque Exacto
trailerInfo (opcional) Un array de objetos, uno para cada remolque Omite un vehículo sin remolques, como un camión de caja.
hazardousGoodsTypes (opcional) Un array que especifica cualquier material peligroso a bordo EXPLOSIVES, GASES, FLAMMABLE, COMBUSTIBLE, ORGANIC, POISON, CORROSIVE, ASPIRATION_HAZARD, ENVIRONMENTAL_HAZARD, OTHER

Cómo usar máscaras de campo

Para obtener los mejores resultados, incluye el encabezado X-Goog-FieldMask en tu solicitud para especificar exactamente los campos que deseas en la respuesta. Las máscaras de campo reducen la latencia y garantizan que recibas campos de advertencia importantes. Como mínimo, siempre incluye routes.travelAdvisory.routeRestrictionsPartiallyIgnored en la máscara de campo, ya que indica si la ruta tiene una o más restricciones que se aplican a tu vehículo.

Para obtener más detalles sobre FieldMasks con la API de Routes, consulta este artículo.

Peajes

Para preferir rutas sin peaje, especifica avoidTolls en la propiedad routeModifiers de una solicitud. Para obtener más información sobre los modificadores de ruta, consulta Cómo especificar las funciones de ruta que se deben evitar.

Si especificas avoidTolls, no se garantiza que las rutas sin peaje estén en la respuesta. En algunos casos, es necesario usar una ruta de peaje para viajar entre el origen y el destino. Si incluyes routes.warnings en la máscara de campo de tu solicitud a la API de Routes, las rutas que contengan rutas de peaje se anotarán en consecuencia dentro de este campo.

Ejemplo completo de solicitud cURL

A continuación, se muestra una solicitud cURL completa para un camión con semirremolque típico. En este ejemplo, se incluyen el extremo, los encabezados y el cuerpo de la solicitud.

curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
 "origin": {
    "location": {
      "latLng": {
        "latitude": 40.883274,
        "longitude": -74.704574
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 40.991920,
        "longitude": -75.183371
      }
    }
  },
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
  "routeModifiers": {
    "vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }]
    }
  }
}'

Cómo interpretar la respuesta de computeRoutes

Una solicitud exitosa a la API de Routes muestra un objeto de respuesta JSON que contiene una o más rutas posibles.

Campos clave de respuesta

  • Geometría de ruta codificada: routes.polyline. Se puede usar para renderizar la ruta en un mapa.
  • Duración estimada del viaje: routes.duration (en segundos). La duración del viaje de enrutamiento de vehículos grandes usa un modelo nuevo entrenado en las velocidades de viaje observadas de camiones reales en la red de rutas. También se puede usar para calcular la hora de llegada estimada agregando la duración estimada del viaje a la hora de salida esperada.
  • Distancia total de la ruta: routes.distanceMeters (en metros).
  • Token de ruta: routes.routeToken. Es un token opaco que representa la ruta calculada exacta. Pasas este token al SDK de Navigation para asegurarte de que el conductor vea la misma ruta específica para camiones. Para obtener más detalles sobre cómo hacerlo, consulta la guía Proporciona navegación paso a paso guía.

Cómo verificar las marcas de seguridad de la ruta

Cuando recibas una respuesta, lo primero que debes hacer es verificar las marcas de seguridad de la ruta. Si una ruta proporcionada contiene una o más restricciones que la hacen inadecuada para el vehículo, encontrarás el campo travelAdvisory.routeRestrictionsPartiallyIgnored establecido en true.

Este campo actúa como una marca para responder la pregunta "¿Se marcó esta ruta por un posible problema?".

  • false(o se omite de la respuesta): La ruta no está marcada. El sistema encontró una ruta que se cree que cumple por completo con los parámetros que proporcionaste en la solicitud.
  • true: La ruta está marcada. El sistema no pudo encontrar una ruta que cumpla por completo con los requisitos y mostró una ruta de "mejor esfuerzo" que podría no ser segura ni legal. Esta ruta debe usarse con extrema precaución.

Ejemplo: Respuesta de computeRoutes

Esta es una respuesta de ejemplo para la solicitud que se muestra arriba. Ten en cuenta que, en el objeto travelAdvisory, no se incluye la marca routeRestrictionsPartiallyIgnored. Esto indica que la ruta no está marcada y se cree que cumple por completo con el perfil del vehículo.

{
  "routes": [
    {
      "distanceMeters": 3426,
      "duration": "312s",
      "travelAdvisory": {},
      "routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
    }
  ]
}

Cómo obtener una matriz de rutas para camiones

Para calcular los tiempos de viaje de muchos viajes potenciales a la vez, usa el extremo computeRouteMatrix para la planificación de alto nivel y compara de manera eficiente los tiempos de viaje y las distancias entre muchos orígenes y destinos. Por ejemplo, puedes usarlo para encontrar el camión más cercano a una nueva ubicación de recolección. Una vez que identifiques el origen del vehículo que deseas usar para tu propósito, puedes emitir una solicitud computeRoutes para obtener los detalles de la ruta y el token de ruta para el vehículo propuesto.

Para usar computeRouteMatrix, especifica el vehicleInfo dentro de cada objeto de origen.

Ejemplo de solicitud

{
  "origins": [
    {
      "waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    },
    {
      "waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    }
  ],
  "destinations": [
    { "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
    { "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
  ],
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}

Ejemplo de respuesta

La respuesta es un array en el que cada objeto contiene la duración y distanceMeters para un par origen-destino.

[
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": {},
    "distanceMeters": 392372,
    "duration": "14037s",
    "condition": "ROUTE_EXISTS"
  },
  { ... }
]

Próximos pasos