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 véhicules de grande taille. 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 l'itinéraire pour les véhicules de grande taille afin de demander des itinéraires, une distance de trajet, un temps de trajet prévu et des heures d'arrivée prévues qui tiennent compte des attributs spécifiques d'un véhicule de grande taille, comme un camion commercial ou un bus de passagers.

Pour savoir comment effectuer des calculs au niveau du parc pour les véhicules de grande taille à l'aide de l'API Route Optimization, consultez la documentation sur l'itinéraire des camions de l'API Route Optimization.

Points abordés

Vous découvrirez comment effectuer les opérations suivantes :

• Créer une requête de routage valide
• Spécifiez les informations sur votre véhicule réel, en utilisant les dimensions, le poids et d'autres caractéristiques.
• Interprétez 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 de véhicules de grande taille. Le routage des véhicules de grande taille 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 routage des véhicules de grande taille 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 s'assurer qu'ils sont sûrs ou légaux. 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 interdites aux véhicules imposants.
• Routes limitées. Dans certains cas, l'API ne peut pas trouver d'itinéraire qui respecte entièrement les restrictions de circulation. Au lieu de cela, il renvoie un itinéraire "optimisé" qui peut toujours traverser des zones restreintes. 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 en utilisant d'autres sources de données. N'utilisez pas un itinéraire signalé comme source unique de vérité pour la planification ou la navigation.
• Fonctionnalités non compatibles : le routage des véhicules de grande taille n'est pas compatible avec les éléments suivants :
  • Prix des péages pour les camions
  • Limitations de vitesse
  • Itinéraire pour les matières radioactives dangereuses
• Limites d'utilisation : toutes les requêtes sont soumises aux limites de requêtes par seconde (RPS) standards.

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

Pour obtenir un itinéraire pour camion, vous 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 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 pour une matrice de points de départ et de destinations, mais ne renvoie pas de polyligne d'itinéraire.

Paramètres de requête clés

Dans le corps de votre requête, vous devez inclure les paramètres suivants pour activer le routage des 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 décrivant 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 des champs. Par exemple, la hauteur totale doit être indiquée en millimètres (totalHeightMm). Étant donné que les dimensions des camions sont souvent exprimées en pieds ou en mètres, une conversion d'unité peut être nécessaire.

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

Lorsque vous convertissez des 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 réelle du véhicule, l'arrondi d'une valeur fractionnaire peut entraîner un itinéraire trop restrictif pour le véhicule.

Exemple :

• Largeur : de nombreuses remorques américaines ont une largeur de 8 pieds et 6 pouces, ce qui correspond à 2 590,8 mm. Arrondir à 2 591 mm indiquerait que le véhicule mesure plus de 8 pieds et 6 pouces, ce qui le classerait comme un véhicule hors gabarit sur les routes américaines. Cela entraînerait alors un itinéraire calculé selon des contraintes sensiblement différentes de celles prévues.
• Hauteur : un itinéraire passant sous un pont de 3,35 mètres ne conviendrait pas à un tracteur routier classique d'une hauteur de 4,11 mètres. Cependant, les petits camions d'environ 3 mètres de long pourraient passer sous le pont. Il est donc essentiel de spécifier précisément les attributs de votre véhicule.

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
      }

vehicleInfo champs d'objet

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

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 FieldMasks 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, l'utilisation d'une route à péage est nécessaire pour se déplacer entre le point de départ et la destination. Si vous incluez routes.warnings dans le masque de champ de votre requête 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 ni de modificateurs supplémentaires pour activer ces comportements.

Calculer un seul itinéraire 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

Voici un exemple de réponse à la requête précédente présentée ci-dessus. Notez que dans l'objet travelAdvisory, l'option routeRestrictionsPartiallyIgnored n'est pas incluse. 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 envoyée au point de terminaison computeRoutes renvoie un objet de réponse JSON contenant un ou plusieurs itinéraires possibles.

Champs de réponse clés

• Géométrie de l'itinéraire encodée : routes.polyline. Cela peut être utilisé pour afficher l'itinéraire sur une carte.
• Durée estimée du trajet : routes.duration (en secondes). La durée du trajet 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. Il peut également être utilisé 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 de routage : 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 les guides du SDK Navigation pour Android ou iOS.

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

Lorsque vous obtenez 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 de flag pour répondre à la question "Cette route est-elle signalée 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 : la route est signalée. Le système n'a pas pu trouver d'itinéraire entièrement conforme et a renvoyé un itinéraire "au mieux" qui n'est peut-être pas sûr ni légal. Cette route doit être utilisée 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é l'origine du véhicule que vous souhaitez utiliser, vous pouvez envoyer une requête computeRoutes pour obtenir les détails de l'itinéraire et le jeton d'itinéraire du véhicule proposé.

Pour utiliser computeRouteMatrix, vous devez spécifier 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 la valeur distanceMeters pour une paire point de départ-destination.

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

Étapes suivantes

• Fournir une navigation détaillée : découvrez comment utiliser routeToken dans le SDK Navigation pour Android ou iOS.
• Effectuer une optimisation au niveau de la flotte : utilisez l'API Route Optimization avec Large Vehicle Routing.
• Documentation de référence de l'API : pour obtenir la liste complète de tous les champs et valeurs possibles, consultez la documentation de référence de l'API Routes.