ShipmentRoute

La ruta de un vehículo se puede descomponer a lo largo del eje temporal de la siguiente manera (suponemos que hay n visitas):

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

Ten en cuenta que distinguimos entre los siguientes tipos de datos:

  • "eventos puntuales", como el inicio y el final del vehículo, y el inicio y el final de cada visita (también conocidos como llegada y partida) Ocurren en un segundo determinado.
  • "intervalos de tiempo", como las visitas en sí y la transición entre visitas Si bien los intervalos de tiempo a veces pueden tener una duración cero, es decir, comenzar y finalizar en el mismo segundo, a menudo tienen una duración positiva.

Invariantes:

  • Si hay n visitas, hay n+1 transiciones.
  • Una visita siempre está rodeada por una transición antes (mismo índice) y una transición después (índice + 1).
  • El inicio del vehículo siempre está seguido de la transición núm. 0.
  • El final del vehículo siempre está precedido por la transición núm.

Si acercamos la imagen, esto es lo que sucede durante un Transition y 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

Por último, a continuación, se muestra cómo se pueden organizar los estados TRAVEL, BREAKS, DELAY y WAIT durante una transición.

  • No se superponen.
  • El DELAY es único y debe ser un período contiguo justo antes de la próxima visita (o el final del vehículo). Por lo tanto, basta con conocer la duración del retraso para conocer su hora de inicio y finalización.
  • Los BREAKS son períodos de tiempo contiguos y no superpuestos. La respuesta especifica la hora de inicio y la duración de cada interrupción.
  • TRAVEL y WAIT son "interrumpibles": se pueden interrumpir varias veces durante esta transición. Los clientes pueden suponer que el viaje se realiza "lo antes posible" y que "esperar" ocupa el tiempo restante.

Un ejemplo (complejo):

                               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     |       |           |         |         ||
  ||     |       |           |       |           |         |         ||
--++-----------------------------------------------------------------++-->
Representación 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
}
Campos
vehicleIndex

integer

Vehículo que realiza la ruta, identificado por su índice en el ShipmentModel de origen.
vehicleLabel

string

Etiqueta del vehículo que realiza esta ruta, igual a ShipmentModel.vehicles(vehicleIndex).label, si se especifica.
vehicleStartTime

string (Timestamp format)

Hora en la que el vehículo comienza su ruta.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
vehicleEndTime

string (Timestamp format)

Fecha y hora en que el vehículo finaliza su ruta.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
visits[]

object (Visit)

Secuencia ordenada de visitas que representa una ruta. visits[i] es la visita i-ésima en la ruta. Si este campo está vacío, se considera que el vehículo no se usa.
transitions[]

object (Transition)

Lista ordenada de transiciones para la ruta.
hasTrafficInfeasibilities

boolean

Cuando OptimizeToursRequest.consider_road_traffic se establece como verdadero, este campo indica que las incoherencias en los horarios de las rutas se predicen con estimaciones de duración del viaje basadas en el tráfico. Es posible que no haya tiempo suficiente para completar el viaje ajustado al tráfico, las demoras y los descansos entre visitas, antes de la primera visita o después de la última, y, aun así, cumplir con los períodos de visita y del vehículo. Por ejemplo:

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

Es probable que la llegada a next_visit se produzca más tarde que su intervalo actual debido al aumento en la estimación del tiempo de viaje travelDuration(previous_visit, next_visit) debido al tráfico. Además, es posible que se fuerce una pausa para que se superponga con una visita debido a un aumento en las estimaciones del tiempo de viaje y a las restricciones del intervalo de tiempo de la visita o la pausa.
routePolyline

object (EncodedPolyline)

Es la representación de polilínea codificada de la ruta. Este campo solo se propaga si OptimizeToursRequest.populate_polylines se establece como verdadero.
breaks[]

object (Break)

Son los descansos programados para el vehículo que realiza esta ruta. La secuencia breaks representa intervalos de tiempo, cada uno comienza en el startTime correspondiente y dura duration segundos.
metrics

object (AggregatedMetrics)

Son las métricas de duración, distancia y carga para esta ruta. Los campos de AggregatedMetrics se suman en todos los ShipmentRoute.transitions o ShipmentRoute.visits, según el contexto.
vehicleFullness

object (VehicleFullness)

Campo VehicleFullness para calcular qué tan cerca están las métricas con límite de sus respectivos límites del vehículo. Sus campos son proporciones entre un campo de métricas con límite (p.ej., AggregatedMetrics.travel_distance_meters) y el límite del vehículo relacionado (p.ej., Vehicle.route_distance_limit).

Experimental: El comportamiento o la existencia de este campo pueden cambiar en el futuro.
routeCosts

map (key: string, value: number)

Costo de la ruta, desglosado por los campos de solicitud relacionados con el costo. Las claves son rutas de acceso a .proto, relativas a la OptimizeToursRequest de entrada, p. ej., "model.shipments.pickups.cost", y los valores son el costo total generado por el campo de costo correspondiente, agregado en toda la ruta. En otras palabras, costs["model.shipments.pickups.cost"] es la suma de todos los costos de retiro en la ruta. Todos los costos definidos en el modelo se informan aquí en detalle, con la excepción de los costos relacionados con TransitionAttributes, que solo se informan de forma agregada a partir del 1/2022.
routeTotalCost

number

Es el costo total de la ruta. Es la suma de todos los costos en el mapa de costos.

Visitar

Visita que se realiza durante una ruta. Esta visita corresponde a un retiro o una entrega de un Shipment.

Representación JSON 
{
  "shipmentIndex": integer,
  "isPickup": boolean,
  "visitRequestIndex": integer,
  "startTime": string,
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "detour": string,
  "shipmentLabel": string,
  "visitLabel": string,
  "visitType": enum (VisitType),
  "injectedSolutionLocationToken": integer
}
Campos
shipmentIndex

integer

Índice del campo shipments en el ShipmentModel de origen.
isPickup

boolean

Si es verdadero, la visita corresponde a un retiro de un Shipment. De lo contrario, corresponde a una entrega.
visitRequestIndex

integer

Índice de VisitRequest en el campo de retiro o entrega del objeto Shipment (consulta isPickup).
startTime

string (Timestamp format)

Fecha y hora en que comienza la visita. Ten en cuenta que es posible que el vehículo llegue antes a la ubicación de la visita. Los períodos coinciden con los de ShipmentModel.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
loadDemands

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

Demanda total de carga de visitas como la suma del envío y la solicitud de visita loadDemands. Los valores son negativos si la visita es una entrega. Las demandas se registran para los mismos tipos que Transition.loads (consulta este campo).
detour

string (Duration format)

Tiempo adicional de desvío debido a los envíos visitados en la ruta antes de la visita y al posible tiempo de espera inducido por los períodos. Si la visita es una entrega, el desvío se calcula a partir de la visita de retiro correspondiente y es igual a lo siguiente:

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

De lo contrario, se calcula a partir del startLocation del vehículo y es igual a lo siguiente:

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

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".
shipmentLabel

string

Copia del Shipment.label correspondiente, si se especifica en el Shipment.
visitLabel

string

Copia del VisitRequest.label correspondiente, si se especifica en el VisitRequest.
visitType

enum (VisitType)

Opcional. Especifica el tipo de visita. Anula el campo Visit.is_pickup.
injectedSolutionLocationToken

integer

Es un token opaco que representa información sobre la ubicación de una visita.

Este campo se puede propagar en las visitas de las rutas de resultados cuando VisitRequest.avoid_u_turns se estableció como verdadero para esta visita o si ShipmentModel.avoid_u_turns se estableció como verdadero en la solicitud OptimizeToursRequest.

Experimental: Consulta https://developers.google.com/maps/tt/route-optimization/experimental/u-turn-avoidance/make-request para obtener más detalles.

VisitType

Indica si la visita es un retiro, una entrega o una visita a un Stop. Las visitas a una Stop solo se utilizan cuando se habilita la optimización multimodal.

Enums
VISIT_TYPE_UNSPECIFIED Tipo de visita sin especificar.
PICKUP_SHIPMENT La visita corresponde a un retiro de envío.
DELIVER_SHIPMENT La visita corresponde a la entrega de un envío.

Transición

Transición entre dos eventos en la ruta. Consulta la descripción de ShipmentRoute.

Si el vehículo no tiene startLocation o endLocation, las métricas de viaje correspondientes son 0.

Representación 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)
    },
    ...
  }
}
Campos
travelDuration

string (Duration format)

Duración del viaje durante esta transición.

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".
travelDistanceMeters

number

Es la distancia recorrida durante la transición.
trafficInfoUnavailable

boolean

Cuando se solicita el tráfico a través de OptimizeToursRequest.consider_road_traffic y no se puede recuperar la información del tráfico para un Transition, este valor booleano se establece en verdadero. Esto puede ser temporal (problema poco frecuente en los servidores de tráfico en tiempo real) o permanente (no hay datos para esta ubicación).
delayDuration

string (Duration format)

Es la suma de las duraciones de la demora aplicadas a esta transición. Si hay alguna, la demora comienza exactamente delayDuration segundos antes del próximo evento (visita o finalización del vehículo). Consulta los TransitionAttributes.delay.

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".
breakDuration

string (Duration format)

Suma de la duración de los cortes que se producen durante esta transición, si corresponde. Los detalles sobre la hora de inicio y la duración de cada corte se almacenan en ShipmentRoute.breaks.

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".
waitDuration

string (Duration format)

Tiempo de espera durante esta transición. La duración de espera corresponde al tiempo de inactividad y no incluye el tiempo de descanso. También ten en cuenta que este tiempo de espera se puede dividir en varios intervalos no contiguos.

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".
totalDuration

string (Duration format)

Es la duración total de la transición, que se proporciona para mayor comodidad. Es igual a lo siguiente:

  • próxima visita startTime (o vehicleEndTime si es la última transición): startTime de esta transición
  • Si ShipmentRoute.has_traffic_infeasibilities es falso, también se cumple lo siguiente: `totalDuration = travelDuration + delayDuration
  • breakDuration + waitDuration".

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".
startTime

string (Timestamp format)

Es la hora de inicio de esta transición.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
routePolyline

object (EncodedPolyline)

Es la representación de polilínea codificada de la ruta que se siguió durante la transición. Este campo solo se propaga si populateTransitionPolylines se establece como verdadero.
routeToken

string

Solo salida. Es un token opaco que se puede pasar al SDK de Navigation para reconstruir la ruta durante la navegación y, en caso de cambio de ruta, respetar la intención original cuando se creó la ruta. Trata este token como un BLOB opaco. No compares su valor entre solicitudes, ya que puede cambiar incluso si el servicio devuelve la misma ruta. Este campo solo se propaga si populateTransitionPolylines se establece como verdadero.
vehicleLoads

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

Cargas de vehículos durante esta transición, para cada tipo que aparece en el Vehicle.load_limits de este vehículo o que tiene un Shipment.load_demands distinto de cero en algún envío realizado en esta ruta.

Las cargas durante la primera transición son las cargas iniciales de la ruta del vehículo. Luego, después de cada visita, los loadDemands de la visita se suman o restan para obtener las cargas de la siguiente transición, según si la visita fue de retiro o de entrega.

EncodedPolyline

Es la representación codificada de una polilínea. Puedes encontrar más información sobre la codificación de polilíneas aquí: https://developers.google.com/maps/documentation/utilities/polylinealgorithm https://developers.google.com/maps/documentation/javascript/reference/geometry#encoding.

Representación JSON 
{
  "points": string
}
Campos
points

string

Es una cadena que representa los puntos codificados de la polilínea.

Receso

Son datos que representan la ejecución de una pausa.

Representación JSON 
{
  "startTime": string,
  "duration": string
}
Campos
startTime

string (Timestamp format)

Es la hora de inicio de un descanso.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
duration

string (Duration format)

Duración de un descanso.

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".

VehicleFullness

VehicleFullness es una métrica que calcula qué tan lleno está un vehículo. Cada campo VehicleFullness se encuentra entre 0 y 1, y se calcula como la proporción entre un campo de métrica con límite (p.ej., AggregatedMetrics.travel_distance_meters) y su límite de vehículo relacionado (p.ej., Vehicle.route_distance_limit), si existe. De lo contrario, la proporción de plenitud permanece sin establecer. Si el límite es 0, el campo se establece en 1. Nota: Cuando una ruta está sujeta a problemas de factibilidad de tráfico, algunos índices de ocupación sin procesar pueden superar el 1.0, p.ej., el vehículo puede exceder su límite de distancia. En estos casos, limitamos los valores de plenitud a 1.0.

Representación JSON 
{
  "maxFullness": number,
  "distance": number,
  "travelDuration": number,
  "activeDuration": number,
  "maxLoad": number,
  "activeSpan": number
}
Campos
maxFullness

number

Es el valor máximo de todos los demás campos de este mensaje.
distance

number

Es la proporción entre AggregatedMetrics.travel_distance_meters y Vehicle.route_distance_limit. Si Vehicle.route_distance_limit no está configurado, este campo tampoco lo estará.
travelDuration

number

Es la proporción entre [AggregatedMetrics.travel_duration_seconds][] y Vehicle.travel_duration_limit. Si Vehicle.travel_duration_limit no está configurado, este campo tampoco lo estará.
activeDuration

number

Es la proporción entre [AggregatedMetrics.total_duration_seconds][] y Vehicle.route_duration_limit. Si Vehicle.route_duration_limit no está configurado, este campo tampoco lo estará.
maxLoad

number

Es la proporción máxima entre todos los tipos de [AggregatedMetrics.max_load][] y sus respectivos Vehicle.load_limits. Si no se configuran todos los campos Vehicle.load_limits, este campo no se configurará.
activeSpan

number

Es la proporción (vehicleEndTime - vehicleStartTime) / (latestVehicleEndTime - earliestVehicleStartTime) para un vehículo determinado. Si el denominador no está presente, se usa (ShipmentModel.global_end_time - ShipmentModel.global_start_time) en su lugar.