ShipmentRoute

L'itinéraire d'un véhicule peut être décomposé en fonction de l'axe temporel, comme ceci (nous supposons qu'il y a n visites):

  |            |            |          |       |  T[2], |        |      |
  | Transition |  Visit #0  |          |       |  V[2], |        |      |
  |     #0     |    aka     |   T[1]   |  V[1] |  ...   | V[n-1] | T[n] |
  |  aka T[0]  |    V[0]    |          |       | V[n-2],|        |      |
  |            |            |          |       | T[n-1] |        |      |
  ^            ^            ^          ^       ^        ^        ^      ^
vehicle    V[0].start   V[0].end     V[1].   V[1].    V[n].    V[n]. vehicle
 start     (arrival)   (departure)   start   end      start    end     end

Notez que nous faisons la différence entre:

  • "Événements ponctuels", tels que les heures de début et de fin du véhicule, et les heures de début et de fin de chaque visite (arrivée et départ). Elles se produisent à une seconde donnée.
  • "Intervalles de temps", comme les visites elles-mêmes et la transition entre les visites Bien que les intervalles de temps puissent parfois avoir une durée nulle (c'est-à-dire qu'ils commencent et se terminent à la même seconde), ils ont souvent une durée positive.

Règles invariantes :

  • S'il y a n visites, il y a n+1 transitions.
  • Une visite est toujours entourée d'une transition avant (même index) et d'une transition après (index + 1).
  • Le démarrage du véhicule est toujours suivi de la transition n° 0.
  • La fin du véhicule est toujours précédée de la transition #n.

Voici ce qui se passe lors d'un Transition et d'un Visit:

---+-------------------------------------+-----------------------------+-->
   |           TRANSITION[i]             |           VISIT[i]          |
   |                                     |                             |
   |  * TRAVEL: the vehicle moves from   |      PERFORM the visit:     |
   |    VISIT[i-1].departure_location to |                             |
   |    VISIT[i].arrival_location, which |  * Spend some time:         |
   |    takes a given travel duration    |    the "visit duration".    |
   |    and distance                     |                             |
   |                                     |  * Load or unload           |
   |  * BREAKS: the driver may have      |    some quantities from the |
   |    breaks (e.g. lunch break).       |    vehicle: the "demand".   |
   |                                     |                             |
   |  * WAIT: the driver/vehicle does    |                             |
   |    nothing. This can happen for     |                             |
   |    many reasons, for example when   |                             |
   |    the vehicle reaches the next     |                             |
   |    event's destination before the   |                             |
   |    start of its time window         |                             |
   |                                     |                             |
   |  * DELAY: *right before* the next   |                             |
   |    arrival. E.g. the vehicle and/or |                             |
   |    driver spends time unloading.    |                             |
   |                                     |                             |
---+-------------------------------------+-----------------------------+-->
   ^                                     ^                             ^
V[i-1].end                           V[i].start                    V[i].end

Enfin, voici comment les éléments TRAVEL, BREAKS, {8/} et WAIT peuvent être organisés lors d'une transition.

  • Ils ne se chevauchent pas.
  • Le délai est unique et doit correspondre à une période contiguë juste avant la prochaine visite (ou l'arrivée du véhicule). Il suffit donc de connaître la durée du délai pour connaître ses heures de début et de fin.
  • Les BREAKS sont des périodes de temps qui se suivent et ne se chevauchent pas. La réponse spécifie l'heure de début et la durée de chaque coupure.
  • TRAVEL et WAIT sont "préemptables" : ils peuvent être interrompus plusieurs fois au cours de cette transition. Les clients peuvent supposer que le voyage a lieu "dès que possible" et que cette "attente" remplit le temps restant.

Exemple (complexe) :

                               TRANSITION[i]
--++-----+-----------------------------------------------------------++-->
  ||     |       |           |       |           |         |         ||
  ||  T  |   B   |     T     |       |     B     |         |    D    ||
  ||  r  |   r   |     r     |   W   |     r     |    W    |    e    ||
  ||  a  |   e   |     a     |   a   |     e     |    a    |    l    ||
  ||  v  |   a   |     v     |   i   |     a     |    i    |    a    ||
  ||  e  |   k   |     e     |   t   |     k     |    t    |    y    ||
  ||  l  |       |     l     |       |           |         |         ||
  ||     |       |           |       |           |         |         ||
--++-----------------------------------------------------------------++-->
Représentation JSON
{
  "vehicleIndex": integer,
  "vehicleLabel": string,
  "vehicleStartTime": string,
  "vehicleEndTime": string,
  "visits": [
    {
      object (Visit)
    }
  ],
  "transitions": [
    {
      object (Transition)
    }
  ],
  "hasTrafficInfeasibilities": boolean,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "breaks": [
    {
      object (Break)
    }
  ],
  "metrics": {
    object (AggregatedMetrics)
  },
  "routeCosts": {
    string: number,
    ...
  },
  "routeTotalCost": number
}
Champs
vehicleIndex

integer

Véhicule effectuant l'itinéraire, identifié par son indice dans la source ShipmentModel.

vehicleLabel

string

Libellé du véhicule effectuant cet itinéraire (valeur égale à ShipmentModel.vehicles(vehicleIndex).label, si spécifié).

vehicleStartTime

string (Timestamp format)

Heure à laquelle le véhicule commence son trajet.

Horodatage au format RFC3339 UTC "Zulu", avec une résolution de l'ordre de la nanoseconde et jusqu'à neuf chiffres décimaux. Exemples : "2014-10-02T15:01:23Z" et "2014-10-02T15:01:23.045123456Z".

vehicleEndTime

string (Timestamp format)

Heure à laquelle le véhicule termine son trajet.

Horodatage au format RFC3339 UTC "Zulu", avec une résolution de l'ordre de la nanoseconde et jusqu'à neuf chiffres décimaux. Exemples : "2014-10-02T15:01:23Z" et "2014-10-02T15:01:23.045123456Z".

visits[]

object (Visit)

Séquence ordonnée de visites représentant un itinéraire. visites[i] correspond à la i-ième visite de l'itinéraire. Si ce champ est vide, le véhicule est considéré comme non utilisé.

transitions[]

object (Transition)

Liste numérotée des transitions pour la route.

hasTrafficInfeasibilities

boolean

Lorsque OptimizeToursRequest.consider_road_traffic est défini sur "true", ce champ indique que des incohérences au niveau des horaires des itinéraires sont prédites à l'aide des estimations de durée de trajet en fonction du trafic. Le temps nécessaire peut être insuffisant pour effectuer le trajet, les retards et les pauses ajustés en fonction du trafic entre les visites, avant ou après la première visite, tout en respectant les horaires de visite et les horaires des véhicules. Par exemple,

  startTime(previous_visit) + duration(previous_visit) +
  travelDuration(previous_visit, next_visit) > startTime(next_visit)

L'arrivée à next_visit se produira probablement plus tard que la période actuelle, en raison de l'augmentation estimée du temps de trajet travelDuration(previous_visit, next_visit) en raison du trafic. En outre, une pause peut se chevaucher avec une visite en raison d'une augmentation des estimations de temps de trajet et des restrictions liées aux périodes de visite ou de pause.

routePolyline

object (EncodedPolyline)

Représentation de l'itinéraire sous forme de polyligne encodée. Ce champ n'est renseigné que si OptimizeToursRequest.populate_polylines est défini sur "true".

breaks[]

object (Break)

Arrêts prévus pour le véhicule effectuant cet itinéraire. La séquence breaks représente des intervalles de temps, chacun commençant à la valeur startTime correspondante et durant duration secondes.

metrics

object (AggregatedMetrics)

Métriques de durée, de distance et de charge pour cet itinéraire. Les champs de AggregatedMetrics sont additionnés pour tous les ShipmentRoute.transitions ou ShipmentRoute.visits, en fonction du contexte.

routeCosts

map (key: string, value: number)

Coût de l'itinéraire, réparti selon les champs de requête liés aux coûts. Les clés sont des chemins proto correspondant à la requête OptimizeToursRequest d'entrée. Exemple : "model.shipments.pickups.cost", et les valeurs correspondent au coût total généré par le champ de coût correspondant, agrégé sur l'ensemble de l'itinéraire. En d'autres termes, la valeur "cost["model.shipments.pickups.cost"] correspond à la somme de tous les coûts de retrait sur l'itinéraire. Tous les coûts définis dans le modèle sont indiqués ici en détail, à l'exception des coûts liés aux TransitionAttributes, qui ne sont indiqués que de manière agrégée en date du 1er janvier 2022.

Objet contenant une liste de paires "key": value. Exemple : { "name": "wrench", "mass": "1.3kg", "count": "3" }.

routeTotalCost

number

Coût total de l'itinéraire. Somme de tous les coûts dans la carte des coûts.

Accéder à la page

Visite effectuée sur un itinéraire. Cette visite correspond à la prise en charge ou à la livraison d'un Shipment.

Représentation JSON
{
  "shipmentIndex": integer,
  "isPickup": boolean,
  "visitRequestIndex": integer,
  "startTime": string,
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "detour": string,
  "shipmentLabel": string,
  "visitLabel": string
}
Champs
shipmentIndex

integer

Index du champ shipments dans la source ShipmentModel.

isPickup

boolean

Si la valeur est "true", la visite correspond à la prise en charge d'un Shipment. Sinon, elle correspond à une diffusion.

visitRequestIndex

integer

Index de VisitRequest dans le champ de retrait ou de livraison de Shipment (voir isPickup).

startTime

string (Timestamp format)

Heure de début de la visite. Notez qu'il est possible que le véhicule arrive plus tôt au lieu de la visite. Les heures sont cohérentes avec les ShipmentModel.

Horodatage au format RFC3339 UTC "Zulu", avec une résolution de l'ordre de la nanoseconde et jusqu'à neuf chiffres décimaux. Exemples : "2014-10-02T15:01:23Z" et "2014-10-02T15:01:23.045123456Z".

loadDemands

map (key: string, value: object (Load))

Nombre total de demandes de chargement de visites, calculé comme suit : somme des livraisons et des demandes de visite (loadDemands). Les valeurs sont négatives si la visite correspond à une livraison. Les demandes sont signalées pour les mêmes types que Transition.loads (voir ce champ).

Objet contenant une liste de paires "key": value. Exemple : { "name": "wrench", "mass": "1.3kg", "count": "3" }.

detour

string (Duration format)

Détour supplémentaire en raison du nombre de cargaisons visitées sur l'itinéraire avant la visite et du temps d'attente potentiel induit par les fenêtres de temps. Si la visite est une livraison, le détour est calculé à partir de la visite de prise en charge correspondante et est égal à:

startTime(delivery) - startTime(pickup)
- (duration(pickup) + travel duration from the pickup location
to the delivery location).

Sinon, elle est calculée à partir du startLocation du véhicule et est égale à:

startTime - vehicleStartTime - travel duration from
the vehicle's `startLocation` to the visit.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"

shipmentLabel

string

Copie du Shipment.label correspondant, si spécifié dans Shipment.

visitLabel

string

Copie du VisitRequest.label correspondant, si spécifié dans VisitRequest.

Transition

Transition entre deux événements sur la route. Consultez la description de ShipmentRoute.

Si le véhicule n'a pas de startLocation ni de endLocation, les métriques de trajet correspondantes sont égales à 0.

Représentation JSON
{
  "travelDuration": string,
  "travelDistanceMeters": number,
  "trafficInfoUnavailable": boolean,
  "delayDuration": string,
  "breakDuration": string,
  "waitDuration": string,
  "totalDuration": string,
  "startTime": string,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "vehicleLoads": {
    string: {
      object (VehicleLoad)
    },
    ...
  }
}
Champs
travelDuration

string (Duration format)

Durée du voyage pendant cette transition.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"

travelDistanceMeters

number

Distance parcourue pendant la transition.

trafficInfoUnavailable

boolean

Lorsque le trafic est demandé via OptimizeToursRequest.consider_road_traffic et que les informations sur le trafic n'ont pas pu être récupérées pour un Transition, cette valeur booléenne est définie sur "true". Il peut s'agir d'un problème temporaire (rares incidents sur les serveurs de trafic en temps réel) ou permanent (aucune donnée pour cet emplacement).

delayDuration

string (Duration format)

Somme des délais appliqués à cette transition. Le cas échéant, le délai commence exactement delayDuration secondes avant l'événement suivant (visite ou fin du véhicule). Consultez les TransitionAttributes.delay.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"

breakDuration

string (Duration format)

Durée totale des coupures survenues pendant cette transition, le cas échéant. Les détails concernant l'heure de début et la durée de chaque coupure sont stockés dans ShipmentRoute.breaks.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"

waitDuration

string (Duration format)

Temps d'attente durant cette transition. La durée d'attente correspond au temps d'inactivité et n'inclut pas le temps de pause. Notez également que ce temps d'attente peut être divisé en plusieurs intervalles non contigus.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"

totalDuration

string (Duration format)

Durée totale de la transition, indiquée pour plus de commodité. Elle est égale à:

  • visite suivante startTime (ou vehicleEndTime s'il s'agit de la dernière transition) : startTime de cette transition.
  • Si ShipmentRoute.has_traffic_infeasibilities est défini sur "false", les conditions suivantes s'appliquent également: `totalDuration = TravelDuration + delayDuration
  • "breakDuration + waitDuration".

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"

startTime

string (Timestamp format)

Heure de début de cette transition.

Horodatage au format RFC3339 UTC "Zulu", avec une résolution de l'ordre de la nanoseconde et jusqu'à neuf chiffres décimaux. Exemples : "2014-10-02T15:01:23Z" et "2014-10-02T15:01:23.045123456Z".

routePolyline

object (EncodedPolyline)

Représentation polyligne encodée de l'itinéraire suivi pendant la transition. Ce champ n'est renseigné que si populateTransitionPolylines est défini sur "true".

vehicleLoads

map (key: string, value: object (VehicleLoad))

Les chargements de véhicules au cours de cette transition, pour chaque type qui apparaît dans le Vehicle.load_limits de ce véhicule, ou dont la valeur Shipment.load_demands est différente de zéro pour une livraison effectuée sur cet itinéraire.

Les chargements effectués lors de la première transition sont les chargements de départ de l'itinéraire du véhicule. Ensuite, après chaque visite, les loadDemands de la visite sont ajoutés ou soustraits pour que la transition suivante se charge, selon qu'il s'agit d'une visite avec retrait ou livraison.

Objet contenant une liste de paires "key": value. Exemple : { "name": "wrench", "mass": "1.3kg", "count": "3" }.

EncodedPolyline

Représentation encodée d'une polyligne. Pour en savoir plus sur l'encodage des polylignes, consultez cette page: https://developers.google.com/maps/documentation/utilities/polylinealgorithm https://developers.google.com/maps/documentation/javascript/reference/geometry#encoding.

Représentation JSON
{
  "points": string
}
Champs
points

string

Chaîne représentant les points encodés de la polyligne.

Pause

Données représentant l'exécution d'une coupure.

Représentation JSON
{
  "startTime": string,
  "duration": string
}
Champs
startTime

string (Timestamp format)

Heure de début de la pause.

Horodatage au format RFC3339 UTC "Zulu", avec une résolution de l'ordre de la nanoseconde et jusqu'à neuf chiffres décimaux. Exemples : "2014-10-02T15:01:23Z" et "2014-10-02T15:01:23.045123456Z".

duration

string (Duration format)

Durée d'une pause.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"