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 envois sont attribués à des véhicules ou peuvent être ignorés 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[] sont les itinéraires de chaque véhicule avec les livraisons 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.

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

  1. skippedShipments[] répertorie les envois qui ne sont effectués 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 particulier de la requête. Voici quelques propriétés importantes de ShipmentRoute liées à son Vehicle correspondant :

  • vehicleIndex est l'index basé sur zéro de 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 trajet.
  • vehicleEndTime est 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": {
        ...
      },
      ...
    }
  ],
  ...
}

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

  • 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 au montant de chargement demandé pour effectuer le 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 est 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 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 est 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 de collecte et de livraison et la documentation de référence sur 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 est le 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. Les expéditions obligatoires peuvent toujours être ignorées si leurs performances ne sont pas réalisables dans les contraintes spécifiées. 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 au temps total que les véhicules passent en transit pendant qu'ils effectuent 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 prises par les véhicules pendant leurs trajets.
  • visitDuration correspond au temps total que les véhicules passent à effectuer des visites pendant 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 charge maximale transportée par les véhicules à tout moment de leur itinéraire.

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