Interpréter la réponse

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

L'API Route Optimization renvoie des itinéraires pour les véhicules de la requête correspondante. Les expéditions sont attribuées à des 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 de premier niveau principales :

  • 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.
  • metrics sont des métriques agrégées pour l'ensemble de la réponse, pour tous les véhicules et plans de route. Les métriques de niveau supérieur contiennent les mêmes propriétés que les métriques par route, avec des valeurs agrégées pour toutes les routes.

Il est possible que certaines propriétés ne soient pas toujours renseignées en fonction des résultats de l'optimisation :

  1. skippedShipments[] liste les expéditions qui ne sont effectuées par aucun véhicule. Un envoi peut être ignoré s'il ne peut pas être effectué dans les limites spécifiées ou si le coût de l'envoi dépasse son coût de pénalité. Par exemple, si l'enlèvement ou la livraison d'un colis a une timeWindow très courte, il peut être impossible ou peu rentable pour un véhicule d'effectuer la visite pendant le créneau horaire requis.
  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.

Propriétés de la route

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

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

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": {
        ...
      },
      ...
    }
  ],
  ...
}

Chaque ShipmentRoute inclut une liste ordonnée de visits que le véhicule doit effectuer. Chaque Visit (REST, gRPC) représente un VisitRequest (REST, gRPC) de la requête correspondante. Voici quelques propriétés importantesVisit :

  • shipmentIndex correspond à l'index de base 0 de l'envoi auquel appartient cette visite dans la requête correspondante.
  • isPickup est défini sur "true" lorsqu'une visite est un retrait et sur "false" lorsqu'une visite est une livraison. Les réponses REST omettent cette propriété lorsque la valeur est "false".
  • visitRequestIndex correspond à l'index de base zéro de VisitRequest à partir de Shipment.pickups ou Shipment.deliveries dans la requête correspondante que Visit représente. Les réponses REST omettent cette propriété lorsque la valeur est nulle.
  • startTime correspond à l'heure de début prévue de la visite.
  • loadDemands mappe le type de chargement à la quantité de chargement requise pour terminer Visit. Les quantités de chargement sont négatives pour les visites de livraison, ce qui signifie que la charge est 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 les trajets entre les visits pour un véhicule donné. Les propriétés importantes des messages Transition (REST, gRPC) incluent :

  • startTime correspond à l'heure à laquelle le véhicule commencera la transition.
  • travelDuration correspond à la durée pendant laquelle le véhicule doit rouler pour effectuer la transition.
  • travelDistanceMeters correspond à la distance en mètres que le véhicule doit parcourir pour terminer la transition.
  • trafficInfoUnavailable indique si des données sur le trafic sont disponibles pour la transition.
  • waitDuration représente le temps d'inactivité du véhicule avant qu'il puisse démarrer sa prochaine Visit. Cela peut être dû à la start_time des Visit suivants.
  • 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 Optimisation de l'ordre des arrêts pour les collectes et les livraisons et la documentation de référence ShipmentRoute (REST, gRPC). Pour en savoir plus sur les propriétés routePolyline et routeToken d'un message Transition, consultez Polylignes de transition et jetons de route.

Propriétés des métriques

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

  • totalCost correspond au coût total encouru pour effectuer les itinéraires. Pour en savoir plus sur les coûts, consultez Paramètres du modèle de coûts.
  • usedVehicleCount correspond au nombre total de véhicules utilisés dans la solution. Les véhicules peuvent avoir des itinéraires 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 encouru si l'expédition est ignorée. Il est toujours possible d'ignorer les expéditions obligatoires si leurs performances ne sont pas réalisables en raison de contraintes spécifiques. Pour en savoir plus sur les coûts, consultez Paramètres du modèle de coûts.

Les 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. La propriété Metrics.aggregatedRouteMetrics contient des métriques agrégées pour tous les ShipmentRoute dans le OptimizeToursResponse. Chaque propriété ShipmentRoute.metrics contient des métriques pour ce ShipmentRoute spécifique.

Voici quelques propriétés importantes de AggregatedMetrics :

  • performedShipmentCount correspond au nombre d'expéditions effectuées par les véhicules sur l'ensemble de leurs itinéraires.
  • travelDuration correspond à la durée totale pendant laquelle les véhicules sont en transit pour effectuer leurs itinéraires.
  • waitDuration correspond au temps total passé par les véhicules à attendre pendant qu'ils effectuent 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 à la durée totale des pauses des véhicules lors de l'exécution de leurs itinéraires.
  • visitDuration correspond à la durée totale pendant laquelle les véhicules effectuent des visites lors de leurs itinéraires. Il s'agit en fait de la somme de toutes les valeurs VisitRequest.duration pour les VisitRequest correspondant aux Visit attribués au véhicule concerné.
  • totalDuration correspond à la durée totale nécessaire 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 chargement à la quantité de chargement maximale transportée par les véhicules à tout moment sur 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
    }
  }
}

Exemple complet

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

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