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 : Lisez ce guide si vous êtes un développeur qui crée 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 calcul d'itinéraire pour les 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 calcul d'itinéraire pour les 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 les informations sur votre véhicule réel, en utilisant ses dimensions, son 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 calcul d'itinéraire pour les grands véhicules. Le calcul d'itinéraire pour les grands véhicules est disponible pour un nombre limité de clients. Contactez-nous pour demander l'accès

Limites

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

  • Disponibilité géographique : le calcul d'itinéraire pour les grands véhicules est disponible dans les 48 États contigus des États-Unis (disponibilité générale) et au Japon (expérimental). Il n'est pas disponible en Alaska, à Hawaï ni dans les territoires des États-Unis.
  • Conseils et sécurité pour les conducteurs. 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. Il n'est pas garanti que les itinéraires soient adaptés au véhicule. 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 circulation. Elle renvoie alors 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 votre itinéraire avec soin, idéalement en utilisant 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 : le calcul d'itinéraire pour les grands véhicules n'est pas compatible avec les éléments suivants :
    • Prix des péages pour les camions
    • Limitations de vitesse
    • Calcul d'itinéraire 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 un camion

Pour obtenir un itinéraire pour un 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. Les concepts de cette section s'appliquent aux requêtes d'itinéraire unique et de matrice d'itinéraires.

Points de terminaison

Vous pouvez utiliser deux points de terminaison pour le calcul d'itinéraire pour les camions :

  • computeRoutes: calcule un itinéraire unique 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 paramètres suivants pour activer le calcul d'itinéraire pour les camions :

  • 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 les attributs du 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 caractéristiques 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' 6", ce qui correspond à 2 590,8 mm. L'arrondi à 2 591 mm indiquerait que le véhicule mesure plus de 8' 6", 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' ne conviendrait pas à un semi-remorque classique d'une hauteur de 13,5'. Cependant, les camions-fourgons plus petits d'environ 10' pourraient passer sous le pont. Il est donc essentiel de spécifier les attributs de votre véhicule avec précision.

Diagramme 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éhicules et de charges 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 combinée totale du véhicule et de toutes les remorques. En millimètres, arrondi à l'entier inférieur.
totalWeightKg Poids total autorisé en charge (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-fourgon.
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 les champs de conseils 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.

Autres comportements de routage

Lorsque vous définissez travelMode sur TRUCK, l'API optimise automatiquement l'itinéraire pour la maniabilité des grands véhicules. Les itinéraires générés évitent les demi-tours et privilégient fortement les autoroutes et les voies rapides par rapport aux routes plus petites. Vous n'avez pas besoin de définir de paramètres ou de modificateurs supplémentaires pour activer ces comportements.

Calculer un itinéraire unique avec computeRoutes

Utilisez le point de terminaison computeRoutes pour calculer un itinéraire spécifique aux camions entre un point de départ et une destination.

Exemple de requête computeRoutes

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

Exemple de réponse computeRoutes

Il s'agit d'un exemple de réponse à la requête précédente affiché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 aux attributs du véhicule.

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

Interpréter la réponse computeRoutes

Une requête réussie au point de terminaison computeRoutes 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 calcul d'itinéraire pour les grands véhicules utilise un nouveau modèle entraîné sur les vitesses de déplacement 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 exact calculé. Vous transmettez ce jeton au SDK Navigation pour vous assurer que le conducteur voit le même itinéraire spécifique au camion. Pour en savoir plus, consultez les guides du SDK Navigation pour Android ou iOS.
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 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 n'est peut-être pas sûr ou légal. Cet itinéraire doit être utilisé avec une extrême prudence.

Calculer une matrice d'itinéraires (computeRouteMatrix)

Utilisez le point de terminaison computeRouteMatrix pour 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 origin plutôt qu'à la racine de la requête.

Exemple de requête 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"
}

Exemple de réponse computeRouteMatrix

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