Générer des itinéraires et des heures d'arrivée prévues pour les véhicules de grande taille

À qui s'adresse ce guide ? Ce guide s'adresse aux développeurs qui créent des services de planification et d'exécution de trajets à l'aide de camions ou d'autres grands véhicules. Les cas d'utilisation pertinents incluent le calcul des temps de trajet et des distances, le calcul des heures d'arrivée prévues ou la génération d'itinéraires qui seront utilisés par une application de navigation.

Contenu de ce guide : ce guide explique comment utiliser l'API Routes avec le routage pour grands véhicules afin de demander des itinéraires, des distances de trajet, des temps de trajet prévus et des heures d'arrivée prévues qui tiennent compte des attributs spécifiques d'un grand véhicule, tel qu'un camion commercial ou un bus de passagers.

Pour savoir comment effectuer des calculs au niveau de la flotte pour les grands véhicules à l'aide de l'API Route Optimization, consultez la documentation sur le routage pour camions avec l'API Route Optimization.

Points abordés

Vous apprendrez à effectuer les opérations suivantes :

  • Créer une requête de routage valide.
  • Spécifier un profil de véhicule pour votre véhicule réel, en utilisant les dimensions, le poids et d'autres caractéristiques.
  • Interpréter la réponse, y compris le jeton d'itinéraire et les indicateurs de sécurité du trajet.

Prérequis

  1. Votre projet Google Cloud doit être créé et l'API Routes doit être activée.
  2. Votre projet doit être provisionné pour le routage pour grands véhicules. Contactez votre représentant Google pour effectuer cette étape.

Limites

Avant de commencer, vous devez connaître les limites et exigences suivantes.

  • Disponibilité géographique : le routage pour grands véhicules n'est disponible que dans les 48 États contigus des États-Unis.
  • Le routage pour grands véhicules est une offre en Preview. Les conducteurs ne doivent pas se fier uniquement aux itinéraires renvoyés par cette API pour être en sécurité ou respecter la loi. Les itinéraires ne sont pas garantis d'être adaptés au véhicule, et les suivre peut exposer les conducteurs à des dangers tels que des ponts bas ou des routes où les grands véhicules sont interdits.
  • Itinéraires limités. Dans certains cas, l'API ne peut pas trouver d'itinéraire qui respecte pleinement les restrictions de trajet. Au lieu de cela, elle renvoie un itinéraire "limité" qui peut toujours traverser des zones à circulation restreinte. La réponse de l'API Routes signale clairement ces itinéraires dans le champ routeRestrictionsPartiallyIgnored. Dans ce cas, planifiez soigneusement votre itinéraire, idéalement à l'aide d'autres données sources. N'utilisez pas un itinéraire signalé comme source unique de vérité pour la planification ou la navigation.
  • Fonctionnalités non compatibles : nous nous efforçons d'ajouter davantage de fonctionnalités à cette offre, mais le routage pour grands véhicules n'est pas compatible avec les éléments suivants :
    • Prix des péages pour les camions
    • Limitations de vitesse
    • Routage pour les matières dangereuses radioactives
  • Limites d'utilisation : toutes les requêtes sont soumises aux limites standard de requêtes par seconde (RPS).

Créer une requête d'itinéraire pour camion

Pour obtenir un itinéraire pour camion, envoyez une requête HTTPS à un point de terminaison de l'API Routes avec des paramètres spécifiques décrivant votre véhicule.

Points de terminaison

Vous pouvez utiliser deux points de terminaison pour le routage des camions :

  • computeRoutes: calcule un seul itinéraire entre un point de départ et une destination.
  • computeRouteMatrix: calcule la distance et la durée d'une matrice de points de départ et de destinations, mais ne renvoie pas de polyligne d'itinéraire.

Paramètres clés de la requête

Dans le corps de votre requête, vous devez inclure les éléments suivants :

  • travelMode: définissez cette valeur sur TRUCK.
  • routingPreference: définissez cette valeur sur TRAFFIC_AWARE_OPTIMAL.
  • routeModifiers: cet objet contient l'objet vehicleInfo dans lequel vous définissez les attributs de votre véhicule. L'objet vehicleInfo est décrit en détail ci-dessous.

Spécifier un profil de véhicule

Pour envoyer une requête, vous devez fournir un corps de requête avec un objet vehicleInfo qui décrit votre véhicule. Considérez ces informations comme une spécification qui correspond aux détails physiques de votre véhicule réel. Le service a besoin de ces informations pour renvoyer des itinéraires qui tiennent compte des restrictions routières en fonction des attributs de votre véhicule.

Mesures du véhicule

Indiquez le poids du véhicule en kilogrammes et ses dimensions en millimètres, comme indiqué par les noms de champs. Par exemple, la hauteur totale doit être fournie en millimètres (totalHeightMm). Étant donné que les dimensions des camions sont souvent exprimées en pieds ou en mètres, cela peut nécessiter une conversion d'unité.

Conversion du système impérial au système métrique

Lors de la conversion d'unités impériales, tenez toujours compte des dimensions spécifiques de votre véhicule ainsi que des limites de taille standard des routes et des passages souterrains. Cela peut être particulièrement important avec les valeurs fractionnaires. Selon la taille du véhicule réel, l'arrondi d'une valeur fractionnaire peut entraîner un routage trop restrictif pour le véhicule.

Exemple :

  • Largeur : de nombreuses remorques américaines ont une largeur de 8 pieds 6 pouces, ce qui correspond à 2 590,8 mm. L'arrondi à 2 591 mm indiquerait que le véhicule mesure plus de 8 pieds 6 pouces, ce qui le classerait comme véhicule surdimensionné sur les routes américaines. L'itinéraire serait alors calculé selon des contraintes sensiblement différentes de celles prévues.
  • Hauteur : un itinéraire passant sous un pont de 11 pieds ne conviendrait pas à un semi-remorque classique d'une hauteur de 13,5 pieds. Toutefois, les camions plus petits d'environ 10 pieds pourraient passer sous le pont. Par conséquent, il est essentiel de spécifier les attributs de votre véhicule avec précision.

Schéma illustrant les dimensions d'un camion par rapport à celles d'un passage souterrain

Voici un extrait de code qui montre un exemple d'objet vehicleInfo :

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

Champs de l'objet vehicleInfo

Le tableau suivant présente toutes les définitions de véhicule et de charge que vous pouvez envoyer avec la requête.

Champ Description Remarques / Valeurs
totalHeightMm Hauteur maximale du véhicule. En millimètres, arrondi à l'entier inférieur. Pour en savoir plus sur l'arrondi, consultez Conversion du système impérial au système métrique.
totalWidthMm Largeur maximale du véhicule. En millimètres, arrondi à l'entier inférieur.
totalLengthMm Longueur totale combinée du véhicule et de toutes les remorques. En millimètres, arrondi à l'entier inférieur.
totalWeightKg Poids total du véhicule (y compris les remorques et la charge). En kilogrammes, arrondi à l'entier inférieur.
totalAxleCount Nombre total d'essieux sur le véhicule et toutes les remorques. Exact.
trailerInfo (facultatif) Tableau d'objets, un pour chaque remorque. Omettez-le pour un véhicule sans remorque, comme un camion.
hazardousGoodsTypes (facultatif) Tableau spécifiant les matières dangereuses à bord. EXPLOSIVES, GASES, FLAMMABLE, COMBUSTIBLE, ORGANIC, POISON, CORROSIVE, ASPIRATION_HAZARD, ENVIRONMENTAL_HAZARD, OTHER

Utiliser des masques de champ

Pour obtenir des résultats optimaux, incluez l'en-tête X-Goog-FieldMask dans votre requête afin de spécifier exactement les champs que vous souhaitez inclure dans la réponse. Les masques de champ réduisent la latence et vous permettent de recevoir des champs d'avis importants. Au minimum, incluez toujours routes.travelAdvisory.routeRestrictionsPartiallyIgnored dans le masque de champ, car cela indique si l'itinéraire comporte une ou plusieurs restrictions qui s'appliquent à votre véhicule.

Pour en savoir plus sur les masques de champ avec l'API Routes, consultez cet article.

Sections à péage

Pour privilégier les itinéraires sans péage, spécifiez avoidTolls dans la propriété routeModifiers d'une requête. Pour en savoir plus sur les modificateurs d'itinéraire, consultez Spécifier les caractéristiques d'itinéraire à éviter.

La spécification de avoidTolls ne garantit pas que les itinéraires sans péage seront inclus dans la réponse. Dans certains cas, il est nécessaire d'emprunter une route à péage pour se rendre du point de départ à la destination. Si vous incluez routes.warnings dans le masque de champ de votre requête d'API Routes, les itinéraires contenant des routes à péage seront annotés en conséquence dans ce champ.

Exemple de requête curl complète

Voici une requête curl complète pour un semi-remorque classique. Cet exemple inclut le point de terminaison, les en-têtes et le corps de la requête.

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

Interpréter la réponse computeRoutes

Une requête réussie adressée à l'API Routes renvoie un objet de réponse JSON contenant un ou plusieurs itinéraires possibles.

Champs clés de la réponse

  • Géométrie d'itinéraire encodée : routes.polyline. Elle peut être utilisée pour afficher l'itinéraire sur une carte.
  • Durée estimée du trajet : routes.duration (en secondes). La durée du trajet pour le routage pour grands véhicules utilise un nouveau modèle entraîné sur les vitesses de trajet observées des camions réels sur le réseau routier. Elle peut également être utilisée pour calculer l'heure d'arrivée prévue en ajoutant la durée estimée du trajet à l'heure de départ prévue.
  • Distance totale de l'itinéraire : routes.distanceMeters (en mètres).
  • Jeton d'itinéraire : routes.routeToken. Il s'agit d'un jeton opaque qui représente l'itinéraire calculé exact. Vous transmettez ce jeton au SDK Navigation pour vous assurer que le conducteur voit le même itinéraire spécifique aux camions. Pour en savoir plus, consultez le guide Fournir un itinéraire détaillé.

Vérifier les indicateurs de sécurité de l'itinéraire

Lorsque vous recevez une réponse, la première chose à faire est de vérifier les indicateurs de sécurité de l'itinéraire. Si un itinéraire fourni contient une ou plusieurs restrictions qui le rendent inadapté au véhicule, le champ travelAdvisory.routeRestrictionsPartiallyIgnored est défini sur true.

Ce champ sert d'indicateur pour répondre à la question : "Cet itinéraire est-il signalé pour un problème potentiel ?"

  • false(ou omis de la réponse) : l'itinéraire n'est pas signalé. Le système a trouvé un itinéraire qui est considéré comme entièrement conforme aux paramètres que vous avez fournis dans la requête.
  • true: l'itinéraire est signalé. Le système n'a pas pu trouver d'itinéraire entièrement conforme et a renvoyé un itinéraire "limité" qui peut ne pas être sûr ou légal. Cet itinéraire doit être utilisé avec une extrême prudence.

Exemple de réponse computeRoutes

Voici un exemple de réponse à la requête présentée ci-dessus. Notez que dans l'objet travelAdvisory, l'indicateur routeRestrictionsPartiallyIgnored n'est pas inclus. Cela indique que l'itinéraire n'est pas signalé et qu'il est considéré comme entièrement conforme au profil du véhicule.

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

Obtenir une matrice d'itinéraires pour camions

Pour calculer les temps de trajet de nombreux trajets potentiels à la fois, utilisez le point de terminaison computeRouteMatrix pour une planification de haut niveau afin de comparer efficacement les temps de trajet et les distances entre de nombreux points de départ et destinations. Par exemple, vous pouvez l'utiliser pour trouver le camion le plus proche d'un nouveau lieu de prise en charge. Une fois que vous avez identifié le point de départ du véhicule que vous souhaitez utiliser, vous pouvez envoyer une requête computeRoutes afin d'obtenir les détails de l'itinéraire et le jeton d'itinéraire pour le véhicule proposé.

Pour utiliser computeRouteMatrix, spécifiez vehicleInfo dans chaque objet d'origine.

Exemple de requête

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

Exemple de réponse

La réponse est un tableau dans lequel chaque objet contient la durée et distanceMeters pour une paire point de départ/destination.

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

Étapes suivantes