ShipmentRoute

L'itinéraire 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 (c'est-à-dire l'arrivée et le départ). Ils se produisent à un moment précis.
  • "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 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 0.
  • La fin du véhicule est toujours précédée de la transition #n.

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 états 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 continue juste avant la prochaine visite (ou la fin de l'utilisation du véhicule). Il suffit donc de connaître la durée du retard pour connaître son heure de début et de fin.
  • Les PAUSES sont des périodes contiguës et non chevauchantes. La réponse spécifie l'heure de début et la durée de chaque pause.
  • Les états TRAVEL et WAIT sont "préemptables" : ils peuvent être interrompus plusieurs fois pendant cette transition. Les clients peuvent supposer que le voyage a lieu "dès que possible" et que le temps restant est rempli par "attente".

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)
  },
  "vehicleFullness": {
    object (VehicleFullness)
  },
  "routeCosts": {
    string: number,
    ...
  },
  "routeTotalCost": number
}
Champs
vehicleIndex

integer

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

string

Libellé du véhicule effectuant cet itinéraire, égal à ShipmentModel.vehicles(vehicleIndex).label, le cas échéant.
vehicleStartTime

string (Timestamp format)

Heure à laquelle le véhicule commence son trajet.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
vehicleEndTime

string (Timestamp format)

Heure à laquelle le véhicule termine son trajet.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
visits[]

object (Visit)

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

object (Transition)

Liste ordonnée des transitions pour l'itinéraire.
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 est possible que vous n'ayez pas assez de temps pour effectuer les trajets ajustés en fonction du trafic, les pauses et les pauses entre les visites, avant la première visite ou après la dernière visite, tout en respectant les créneaux horaires des visites et des véhicules. 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 plage horaire actuelle en raison de l'augmentation du temps de trajet estimé travelDuration(previous_visit, next_visit) due au trafic. Il est également possible qu'une pause soit forcée de chevaucher une visite en raison d'une augmentation des estimations du temps de trajet et des restrictions liées aux créneaux horaires des visites ou des pauses.
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 prévues 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, selon le contexte.
vehicleFullness

object (VehicleFullness)

Champ VehicleFullness pour calculer la proximité des métriques plafonnées par rapport à leurs limites de véhicule respectives. Ses champs sont des ratios entre un champ de métrique plafonnée (par exemple, AggregatedMetrics.travel_distance_meters) et la limite de véhicule associée (par exemple, Vehicle.route_distance_limit).

Expérimental : le comportement ou l'existence de ce champ peuvent changer à l'avenir.
routeCosts

map (key: string, value: number)

Coût de l'itinéraire, réparti par champs de requête liés aux coûts. Les clés sont des chemins proto, relatifs à l'OptimizeToursRequest d'entrée (par exemple, "model.shipments.pickups.cost"), et les valeurs sont le 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, costs["model.shipments.pickups.cost"] correspond à la somme de tous les coûts d'enlèvement sur l'itinéraire. Tous les coûts définis dans le modèle sont détaillés ici, à l'exception de ceux liés aux TransitionAttributes, qui ne sont agrégés qu'à partir du 01/01/2022.
routeTotalCost

number

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

Consulter

Visite effectuée au cours d'un itinéraire. 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,
  "injectedSolutionLocationToken": integer
}
Champs
shipmentIndex

integer

Index du champ shipments dans la ShipmentModel source.
isPickup

boolean

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

integer

Index de VisitRequest dans le champ "pickup" (retrait) ou "delivery" (livraison) de Shipment (voir isPickup).
startTime

string (Timestamp format)

Heure à laquelle la visite commence. Notez que le véhicule peut arriver plus tôt sur le lieu de la visite. Les heures sont cohérentes avec le ShipmentModel.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
loadDemands

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

La demande de charge de visite totale correspond à la somme de la demande de livraison et de la demande de visite loadDemands. Les valeurs sont négatives si la visite est une livraison. Les demandes sont signalées pour les mêmes types que Transition.loads (voir ce champ).
detour

string (Duration format)

Temps de détour supplémentaire dû aux livraisons visitées sur l'itinéraire avant la visite et au temps d'attente potentiel induit par les créneaux horaires. 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 la 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 le Shipment.
visitLabel

string

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

integer

Jeton opaque représentant des informations sur un lieu visité.

Ce champ peut être renseigné dans les visites des itinéraires de résultats lorsque VisitRequest.avoid_u_turns a été défini sur "true" pour cette visite ou si ShipmentModel.avoid_u_turns a été défini sur "true" dans la requête OptimizeToursRequest.

Expérimental : pour en savoir plus, consultez https://developers.google.com/maps/tt/route-optimization/experimental/u-turn-avoidance/make-request.

Transition

Transition entre deux événements sur l'itinéraire. 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". Cela peut être temporaire (rare problème au niveau des 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 cas échéant, le délai commence exactement delayDuration secondes avant le prochain événement (fin de la visite ou du trajet). 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 survenues pendant cette transition, le cas échéant. Les détails sur l'heure de début et la durée de chaque pause 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 passé à attendre 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 pour plus de commodité. Cela équivaut à :

  • prochaine visite 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 éléments suivants 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.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
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 changement 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))

Charges du véhicule pendant cette transition, pour chaque type qui apparaît dans le Vehicle.load_limits de ce véhicule ou qui a un Shipment.load_demands non nul sur une expédition effectuée sur cet itinéraire.

Les chargements 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 obtenir les charges de la prochaine transition, selon qu'il s'agissait d'un retrait ou d'une livraison.

EncodedPolyline

Représentation encodée d'une polyligne. Pour en savoir plus sur l'encodage des polylignes, consultez les pages suivantes : 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.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
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"

VehicleFullness

VehicleFullness est une métrique qui calcule le taux de remplissage d'un véhicule. Chaque champ VehicleFullness est compris entre 0 et 1. Il est calculé comme le ratio entre un champ de métrique plafonné (par exemple, AggregatedMetrics.travel_distance_meters) et sa limite de véhicule associée (par exemple, Vehicle.route_distance_limit), le cas échéant. Sinon, le ratio de remplissage reste non défini. Si la limite est définie sur 0, le champ est défini sur 1. Remarque : Lorsqu'un itinéraire est soumis à des problèmes de trafic, certains ratios de remplissage bruts peuvent dépasser 1,0 (par exemple, le véhicule peut dépasser sa limite de distance). Dans ce cas, nous limitons les valeurs de remplissage à 1,0.

Représentation JSON 
{
  "maxFullness": number,
  "distance": number,
  "travelDuration": number,
  "activeDuration": number,
  "maxLoad": number,
  "activeSpan": number
}
Champs
maxFullness

number

Maximum de tous les autres champs de ce message.
distance

number

Ratio entre AggregatedMetrics.travel_distance_meters et Vehicle.route_distance_limit. Si Vehicle.route_distance_limit n'est pas défini, ce champ ne le sera pas non plus.
travelDuration

number

Ratio entre [AggregatedMetrics.travel_duration_seconds][] et Vehicle.travel_duration_limit. Si Vehicle.travel_duration_limit n'est pas défini, ce champ ne le sera pas non plus.
activeDuration

number

Ratio entre [AggregatedMetrics.total_duration_seconds][] et Vehicle.route_duration_limit. Si Vehicle.route_duration_limit n'est pas défini, ce champ ne le sera pas non plus.
maxLoad

number

Ratio maximal parmi tous les types de [AggregatedMetrics.max_load][] et leurs Vehicle.load_limits respectifs. Si tous les champs Vehicle.load_limits ne sont pas définis, ce champ ne le sera pas non plus.
activeSpan

number

Ratio (vehicleEndTime - vehicleStartTime) / (latestVehicleEndTime - earliestVehicleStartTime) pour un véhicule donné. Si le dénominateur n'est pas présent, il utilise (ShipmentModel.global_end_time - ShipmentModel.global_start_time) à la place.