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 tiempos y distancias de viaje, el cálculo de las horas de llegada estimadas o la generación de rutas que se usarán en 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.

Si deseas obtener información para 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 la información del vehículo para tu vehículo del mundo real, usando 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. El enrutamiento de vehículos grandes está disponible para un grupo limitado de clientes. Comunícate con nosotros para solicitar acceso

Limitaciones

Antes de comenzar, debes conocer las siguientes limitaciones y requisitos.

  • Disponibilidad geográfica: El enrutamiento de vehículos grandes está disponible en los 48 estados contiguos de Estados Unidos (disponibilidad general) y Japón (experimental). No está disponible en Alaska, Hawái ni en los territorios estadounidenses.
  • Advertencias y seguridad para el conductor. 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 usando 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 admitidas: 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 endpoint de API de Routes con parámetros específicos que describan tu vehículo. Los conceptos de esta sección se aplican a las solicitudes de ruta única y de matriz de rutas.

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 los siguientes parámetros para habilitar el enrutamiento de camiones:

  • travelMode: Configura este valor en TRUCK.
  • routingPreference: Configura 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 atributos del 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). Como 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 y 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 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.

Especificar avoidTolls no garantiza rutas sin peaje en la respuesta. En algunos casos, es necesario usar una ruta con 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.

Otros comportamientos de enrutamiento

Cuando configuras travelMode como TRUCK, la API optimiza automáticamente la ruta para la maniobrabilidad de vehículos grandes. Las rutas generadas evitan los giros en U y prefieren las autopistas interestatales y las autopistas por sobre las rutas más pequeñas. No es necesario que configures parámetros ni modificadores adicionales para habilitar estos comportamientos.

Cómo calcular una sola ruta con computeRoutes

Usa el extremo computeRoutes para calcular una ruta específica para camiones entre un origen y un destino.

Ejemplo de solicitud computeRoutes

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
      }]
    }
  }
}'

Ejemplo de respuesta computeRoutes

Este es un ejemplo de respuesta para la solicitud anterior 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 los atributos del vehículo.

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

Cómo interpretar la respuesta computeRoutes

Una solicitud exitosa al extremo computeRoutes 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 estimada de llegada 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. Este 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, consulta las guías del SDK de Navigation para Android o iOS.
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 y mostró una ruta de "mejor esfuerzo" que podría no ser segura ni legal. Esta ruta debe usarse con extrema precaución.

Cómo calcular una matriz de rutas (computeRouteMatrix)

Usa el extremo computeRouteMatrix para comparar de manera eficiente los tiempos y las distancias de viaje 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, debes especificar vehicleInfo dentro de cada objeto origin en lugar de en la raíz de la solicitud.

Ejemplo de solicitud computeRouteMatrix

{
  "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 computeRouteMatrix

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