Interpréter la réponse

Développeurs de l'Espace économique européen (EEE)

Si votre adresse de facturation se trouve dans l'Espace économique européen, les Conditions d'utilisation de Google Maps Platform pour l'EEE s'appliqueront à votre utilisation des Services à compter du 8 juillet 2025. La fonctionnalité varie selon la région. En savoir plus.

L'API Route Optimization renvoie des itinéraires pour les véhicules dans la requête correspondante. Les expéditions sont attribuées aux véhicules ou peuvent être ignorées en fonction des propriétés de la requête.

Un message OptimizeToursResponse (REST, gRPC) comporte deux propriétés principales de premier niveau :

• routes[] correspond aux itinéraires de chaque véhicule avec les expéditions qui lui sont attribuées. Chaque Route contient des métriques reflétant les propriétés de cet itinéraire individuel.
• metrics correspond aux métriques agrégées pour l'ensemble de la réponse, pour tous les véhicules et tous les plans d'itinéraire. Les métriques de premier niveau contiennent les mêmes propriétés que les métriques par itinéraire, avec des valeurs agrégées sur tous les itinéraires.

Certaines propriétés ne sont pas toujours renseignées en fonction des résultats d'optimisation :

1. skippedShipments[] répertorie les expéditions qui ne sont effectuées par aucun véhicule. Une expédition peut être ignorée si elle ne peut pas être effectuée dans les limites spécifiées ou si le coût de l'expédition dépasse son coût de pénalité. Par exemple, si l'enlèvement ou la livraison d'une expédition a une timeWindow très étroite, il peut être impossible ou non rentable pour un véhicule d'effectuer la visite pendant la période requise.
2. validationErrors[] spécifie les erreurs qui rendent la requête non valide ou impossible à résoudre lorsque le solvingMode de la requête est défini sur VALIDATE_ONLY. En mode DEFAULT_SOLVE normal, les erreurs de validation s'affichent dans un message d'erreur au lieu du corps de la réponse. Notez que le mode de résolution VALIDATE_ONLY peut signaler plusieurs erreurs à la fois, ce qui est utile pour déboguer rapidement les requêtes.

Remarque : Pour interpréter une réponse, la requête correspondante est nécessaire. La réponse contient des références à des entités de la requête, ce qui la rend difficile à interpréter seule. Certains messages tels que Shipment et Vehicle comportent des propriétés de libellé pour faciliter la mise en correspondance des données de requête et de réponse.

Propriétés de l'itinéraire

Chaque routes[] entrée est un ShipmentRoute message (REST, gRPC). Chaque ShipmentRoute représente l'attribution d'itinéraire pour un véhicule spécifique de la requête. Les propriétés ShipmentRoute importantes liées à son Vehicle correspondant incluent les éléments suivants :

• vehicleIndex est l'index basé sur zéro du Vehicle dans le message de requête correspondant. Les réponses REST omettent cette propriété lorsque la valeur est égale à zéro.
• vehicleStartTime correspond à l'heure à laquelle le véhicule doit commencer son itinéraire.
• vehicleEndTime correspond à l'heure à laquelle le véhicule devrait terminer son itinéraire.

Dans une réponse, routes se présente comme suit :

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        ...
      ],
      "transitions": [
        ...
      ],
      "metrics": {
        ...
      },
      ...
    }
  ],
  ...
}

Remarque : Les réponses REST utilisent la représentation JSON des tampons de protocole, qui omet les champs dont la valeur par défaut est celle de leur type respectif et qui ne sont pas compatibles avec le champ présent. Cela signifie que les propriétés entières telles que vehicleIndex sont omises lorsque leurs valeurs sont égales à zéro. Consultez également la documentation officielle sur le mappage JSON des tampons de protocole.

Chaque ShipmentRoute inclut une liste ordonnée de visits que le véhicule effectuera. Chaque Visit (REST, gRPC) représente une VisitRequest (REST, gRPC) de la requête correspondante. Les propriétés Visit importantes incluent les éléments suivants :

• shipmentIndex est l'index basé sur zéro de l'expédition à laquelle appartient cette visite dans la requête correspondante.
• isPickup est défini sur "true" lorsqu'une visite est un enlèvement et sur "false" lorsqu'il s'agit d'une livraison. Les réponses REST omettent cette propriété lorsque la valeur est égale à "false".
• visitRequestIndex est l'index basé sur zéro du VisitRequest de Shipment.pickups ou Shipment.deliveries dans la requête correspondante que représente le Visit. Les réponses REST omettent cette propriété lorsque la valeur est égale à zéro.
• startTime correspond à l'heure à laquelle la visite devrait commencer.
• loadDemands mappe le type de charge à la quantité de charge requise pour effectuer la Visit. Les quantités de charge sont négatives pour les visites de livraison, ce qui représente la charge retirée du véhicule.

Voici un exemple de Visit :

{
  "routes": [
    {
      ...
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        ...
      ],
    },
    ...
  ],
  ...
}

Chaque ShipmentRoute inclut une liste ordonnée de transitions qui représentent le trajet entre les visits pour un véhicule donné. Les propriétés importantes du message Transition (REST, gRPC) incluent les éléments suivants :

• startTime correspond à l'heure à laquelle le véhicule commencera à effectuer la transition.
• travelDuration correspond à la durée pendant laquelle le véhicule doit se déplacer pour effectuer la transition.
• travelDistanceMeters correspond à la distance en mètres que le véhicule doit parcourir pour effectuer la transition.
• trafficInfoUnavailable indique si les données de trafic sont disponibles pour la transition.
• waitDuration représente le temps d'inactivité que le véhicule passe à attendre avant de pouvoir commencer sa prochaine Visit. Cela peut être dû au start_time de la Visit suivante.
• totalDuration correspond à la durée totale de la transition, y compris les temps de trajet, d'attente, de pause et de retard.
• vehicleLoads mappe le type de charge à la quantité de charge transportée par le véhicule pendant cette transition.

Voici un exemple de Transition :

{
  "routes": [
    {
      ...
      "transitions": [
        ...
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        ...
      ],
      ...
    }
  ],
  ...
}

Pour en savoir plus sur la relation entre vists et transitions, consultez la section Optimisation de l'ordre des arrêts d'enlèvement et de livraison et la ShipmentRoute documentation de référence (REST, gRPC). Pour en savoir plus sur les routePolyline et routeToken propriétés d'un Transition message, consultez la section Polylignes de transition et jetons d'itinéraire.

Propriétés des métriques

Le message Metrics (REST, gRPC) résume l'ensemble de la solution. Voici quelques propriétés Metrics importantes :

• totalCost correspond au coût total engendré pour effectuer les itinéraires. Pour en savoir plus sur les coûts, consultez la section Paramètres du modèle de coûts.
• usedVehicleCount correspond au nombre total de véhicules utilisés dans la solution. Les itinéraires des véhicules peuvent être vides lorsque l'optimiseur détermine que leur utilisation n'est pas nécessaire.
• skippedMandatoryShipmentCount correspond au nombre d'expéditions ignorées qui sont "obligatoires". Une expédition obligatoire ne spécifie pas de penaltyCost qui est engendré si l'expédition est ignorée. Les expéditions obligatoires peuvent toujours être ignorées si leurs performances ne sont pas réalisables dans les limites spécifiées. Pour en savoir plus sur les coûts, consultez la section Paramètres du modèle de coûts.

Des métriques supplémentaires sont signalées sous forme de messages AggregatedMetrics (REST, gRPC). Le type de message AggregatedMetrics est utilisé pour la propriété Metrics.aggregatedRouteMetrics et pour la propriété ShipmentRoute.metrics . Metrics.aggregatedRouteMetrics contient des métriques agrégées sur tous les ShipmentRoute dans le OptimizeToursResponse. Chaque ShipmentRoute.metrics propriété contient des métriques pour ce ShipmentRoute spécifique.

Voici quelques propriétés AggregatedMetrics importantes :

• performedShipmentCount correspond au nombre d'expéditions effectuées par les véhicules sur l'ensemble de leurs itinéraires.
• travelDuration correspond au temps total que les véhicules passent en transit pour effectuer leurs itinéraires.
• waitDuration correspond au temps total que les véhicules passent à attendre pour effectuer leurs itinéraires.
• delayDuration correspond au temps de retard total des véhicules. Cette valeur est généralement nulle, sauf si des TransitionAttributes sont utilisés dans la requête.
• breakDuration correspond au temps total que les véhicules passent en pause pour effectuer leurs itinéraires.
• visitDuration correspond au temps total que les véhicules passent à effectuer des visites pour effectuer leurs itinéraires. Il s'agit en fait de la somme de toutes les VisitRequest.duration valeurs pour les VisitRequest correspondant aux Visits attribuées au véhicule applicable.
• totalDuration correspond à la durée totale requise pour effectuer les itinéraires des véhicules.
• travelDistanceMeters correspond à la distance totale parcourue par les véhicules pour effectuer leurs itinéraires.
• maxLoads mappe les types de charge à la quantité de charge maximale transportée par les véhicules à tout moment de leurs itinéraires.

Voici un exemple de message Metrics :

{
  "routes": [
    ...
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}

Important : Si tous les coûts sont égaux à zéro dans les messages Metrics ou ShipmentRoute, il est peu probable que l’optimiseur ait trouvé un ordre optimal pour l’exécution de la Visit. Vous devez spécifier au moins un paramètre de coût, tel que Vehicle.costPerKilometer ou globalDurationCostPerHour. Sinon, l'optimiseur peut renvoyer n'importe quelle solution qui répond aux contraintes spécifiées.

Exemple complet

Voici un exemple de réponse complète à la requête de la section Créer une requête ressemble à :

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        {
          "startTime": "2024-02-13T00:19:31Z",
          "detour": "0s"
        }
      ],
      "transitions": [
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1151s",
          "travelDistanceMeters": 9599,
          "waitDuration": "0s",
          "totalDuration": "1151s",
          "startTime": "2024-02-13T00:19:31Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 1,
        "travelDuration": "2322s",
        "waitDuration": "0s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "0s",
        "totalDuration": "2322s",
        "travelDistanceMeters": 18603
      },
      "routeCosts": {
        "model.vehicles.cost_per_kilometer": 18.603
      },
      "routeTotalCost": 18.603
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}