ShipmentRoute

Le trajet d'un véhicule peut être décomposé, le long de l'axe temporel, comme suit (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 distinction entre:

  • "Événements ponctuels", tels que le début et la fin du trajet du véhicule, ainsi que le début et la fin de chaque visite (arrivée et départ). Ils se produisent à un instant donné.
  • "intervalles de temps", tels que 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 commencer et se terminer à 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 précédée d'une transition (même indice) et suivie d'une transition (indice + 1).
  • Le démarrage du véhicule est toujours suivi de la transition 0.
  • La fin du véhicule est toujours précédée de la transition n.

En zoomant, voici ce qui se passe lors d'une Transition et d'une 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, DELAY et WAIT peuvent être organisés lors d'une transition.

  • Elles ne se chevauchent pas.
  • Le champ DELAY est unique et doit correspondre à une période contiguë juste avant la prochaine visite (ou la fin du véhicule). Il suffit donc de connaître la durée du délai pour connaître son heure de début et de fin.
  • Les PAUSES sont des périodes de temps contiguës et non se chevauchant. La réponse spécifie l'heure de début et la durée de chaque pause.
  • TRAVEL et WAIT sont "préemptables": ils peuvent être interrompus plusieurs fois pendant cette transition. Les clients peuvent supposer que le trajet se fait "dès que possible" et que l'attente occupe 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 le trajet, identifié par son indice dans la source ShipmentModel.
vehicleLabel

string

Libellé du véhicule effectuant ce trajet, égal à ShipmentModel.vehicles(vehicleIndex).label, le cas échéant.
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 itinéraire.

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. visits[i] correspond à la i e visite de l'itinéraire. Si ce champ est vide, le véhicule est considéré comme inutilisé.
transitions[]

object (Transition)

Liste triée des transitions pour le parcours.
hasTrafficInfeasibilities

boolean

Lorsque OptimizeToursRequest.consider_road_traffic est défini sur "true", ce champ indique que les incohérences dans les horaires des itinéraires sont prédites à l'aide d'estimations de la durée du trajet basées sur le trafic. Il se peut que le temps ne soit pas suffisant pour effectuer les trajets, les retards et les pauses ajustés en fonction du trafic entre les visites, avant la première visite ou après la dernière visite, tout en respectant les délais de visite et de véhicule. Par exemple,

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

L'arrivée à next_visit aura probablement lieu plus tard que la période actuelle en raison de l'augmentation de l'estimation du temps de trajet travelDuration(previous_visit, next_visit) en raison du trafic. De plus, une pause peut être forcée de se chevaucher avec une visite en raison d'une augmentation des estimations de temps de trajet et de restrictions concernant les 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)

Pauses planifiées pour le véhicule effectuant cet itinéraire. La séquence breaks représente des intervalles de temps, chacun commençant à l'startTime correspondant 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, selon le contexte.
routeCosts

map (key: string, value: number)

Coût du trajet, réparti par champ de requête lié aux coûts. Les clés sont des chemins proto, par rapport à la requête OptimizeToursRequest d'entrée (par 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ées sur l'ensemble du parcours. En d'autres termes, costs["model.shipments.pickups.cost"] correspond à la somme de tous les coûts de prise en charge 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 à TransitionAttributes, qui ne sont indiqués de manière agrégée qu'à partir de janvier 2022.
routeTotalCost

number

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

Accéder à la page

Visite effectuée lors d'un parcours. Cette visite correspond à un retrait ou à une 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

Indice du champ shipments dans le ShipmentModel source.
isPickup

boolean

Si la valeur est "true", la visite correspond à la récupération d'un Shipment. Sinon, il correspond à une diffusion.
visitRequestIndex

integer

Indice de VisitRequest dans le champ "Pickup" (Retrait) ou "Delivery" (Livraison) de Shipment (voir isPickup).
startTime

string (Timestamp format)

Heure de début de la visite. Notez que le véhicule peut arriver plus tôt sur le lieu de la visite. Les heures sont cohérentes avec le 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))

Demande de charge de visite totale en tant que somme de l'envoi et de la demande de visite loadDemands. Les valeurs sont négatives si la visite correspond à une livraison. Les demandes sont enregistrées pour les mêmes types que Transition.loads (voir ce champ).
detour

string (Duration format)

Temps de déviation supplémentaire en raison des envois visités sur l'itinéraire avant la visite et du temps d'attente potentiel induit par les délais. Si la visite est une livraison, le détour est calculé à partir de la visite de retrait 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 de l'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 de l'Shipment.label correspondante, si elle est spécifiée dans le Shipment.
visitLabel

string

Copie de l'VisitRequest.label correspondante, si elle est spécifiée dans le VisitRequest.

Transition

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

Si le véhicule ne dispose pas de startLocation et/ou 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)
  },
  "routeToken": string,
  "vehicleLoads": {
    string: {
      object (VehicleLoad)
    },
    ...
  }
}
Champs
travelDuration

string (Duration format)

Durée du trajet 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 (rare problème sur les serveurs de trafic en temps réel) ou permanent (aucune donnée pour cet emplacement).
delayDuration

string (Duration format)

Somme des durées de retard appliquées à cette transition. Le délai, le cas échéant, commence exactement delayDuration secondes avant l'événement suivant (fin de la visite ou 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)

Somme de la durée des pauses qui se produisent pendant cette transition, le cas échéant. Les informations sur l'heure de début et la durée de chaque pause sont stockées 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)

Durée d'attente pendant 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, fournie à titre indicatif. Il est égal à:

  • startTime de la prochaine visite (ou vehicleEndTime s'il s'agit de la dernière transition) : startTime de cette transition ;
  • Si ShipmentRoute.has_traffic_infeasibilities est faux, la valeur suivante est également vraie : "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 de la polyligne encodée de l'itinéraire suivi pendant la transition. Ce champ n'est renseigné que si populateTransitionPolylines est défini sur "true".
routeToken

string

Uniquement en sortie. Jeton opaque pouvant être transmis au SDK Navigation pour reconstruire l'itinéraire pendant la navigation et, en cas de recalcul d'itinéraire, respecter l'intention initiale lors de la création de l'itinéraire. Traitez ce jeton comme un blob opaque. Ne comparez pas sa valeur entre les requêtes, car elle peut changer même si le service renvoie exactement le même itinéraire. Ce champ n'est renseigné que si populateTransitionPolylines est défini sur "true".
vehicleLoads

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

Chargements du véhicule pendant cette transition, pour chaque type qui apparaît dans la Vehicle.load_limits de ce véhicule ou qui a une Shipment.load_demands non nulle pour un envoi effectué sur ce trajet.

Les charges lors de la première transition correspondent aux charges de départ du trajet du véhicule. Ensuite, après chaque visite, les loadDemands de la visite sont ajoutés ou soustraits pour obtenir les charges de la prochaine transition, selon que la visite était un retrait ou une livraison.

EncodedPolyline

Représentation encodée d'une polyligne. Pour en savoir plus sur l'encodage des polylignes, consultez les pages https://developers.google.com/maps/documentation/utilities/polylinealgorithm et 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 pause.

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

string (Timestamp format)

Heure de début d'une 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"