ShipmentRoute

La ruta de un vehículo se puede descomponer, a lo largo del eje del tiempo, de la siguiente manera (supón 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 hacemos una distinción entre los siguientes conceptos:

  • "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 salida) Ocurren en un segundo determinado.
  • "intervalos de tiempo", como las visitas en sí y la transición entre ellas. Aunque, a veces, los intervalos de tiempo pueden tener una duración de cero, es decir, comenzar y finalizar en el mismo segundo, a menudo tienen una duración positiva.

Invariables:

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

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, aquí se explica cómo se pueden organizar 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 de la demora para conocer su hora de inicio y finalización.
  • Las PAUSAS son períodos de tiempo contiguos que no se superponen. La respuesta especifica la hora de inicio y la duración de cada descanso.
  • TRAVEL y WAIT son "preemptibles": se pueden interrumpir varias veces durante esta transición. Los clientes pueden suponer que el viaje se realiza “lo antes posible” y que el tiempo restante se dedica a “esperar”.

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)
  },
  "routeCosts": {
    string: number,
    ...
  },
  "routeTotalCost": number
}
Campos
vehicleIndex

integer

Es el 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.

Una marca de tiempo en formato RFC3339 UTC “Zulú”, con una resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z" y "2014-10-02T15:01:23.045123456Z".
vehicleEndTime

string (Timestamp format)

Hora a la que el vehículo termina su ruta.

Una marca de tiempo en formato RFC3339 UTC “Zulú”, con una resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z" y "2014-10-02T15:01:23.045123456Z".
visits[]

object (Visit)

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

object (Transition)

Es la lista ordenada de transiciones de la ruta.
hasTrafficInfeasibilities

boolean

Cuando OptimizeToursRequest.consider_road_traffic se establece en verdadero, este campo indica que se predicen inconsistencias en los horarios de las rutas con estimaciones de duración del viaje basadas en el tráfico. Es posible que no haya tiempo suficiente para completar los viajes ajustados al tráfico, las demoras y las pausas entre visitas, antes de la primera visita o después de la última, y cumplir con los horarios de las visitas y los vehículos. 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 el período actual debido al aumento de la estimación del tiempo de viaje travelDuration(previous_visit, next_visit) debido al tráfico. Además, es posible que una pausa se superponga con una visita debido a un aumento en las estimaciones de tiempo de viaje y las restricciones de los períodos de visita o descanso.
routePolyline

object (EncodedPolyline)

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

object (Break)

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

object (AggregatedMetrics)

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

map (key: string, value: number)

Es el costo de la ruta, desglosado por campos de solicitud relacionados con el costo. Las claves son rutas de proto, en relación con la entrada OptimizeToursRequest, 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 registran en detalle aquí, a excepción de los costos relacionados con TransitionAttributes, que solo se registran de forma agregada a partir de 1/2022.
routeTotalCost

number

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

Visitar

Es una visita realizada durante una ruta. Esta visita corresponde a la recolección o 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
}
Campos
shipmentIndex

integer

Es el índice del campo shipments en el ShipmentModel de origen.
isPickup

boolean

Si es verdadero, la visita corresponde a la recolección de un Shipment. De lo contrario, corresponde a una publicación.
visitRequestIndex

integer

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

string (Timestamp format)

Hora en la que comienza la visita. Ten en cuenta que el vehículo puede llegar antes a la ubicación de la visita. Los tiempos son coherentes con los de ShipmentModel.

Una marca de tiempo en formato RFC3339 UTC “Zulú”, con una resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z" y "2014-10-02T15:01:23.045123456Z".
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 solicitudes 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

Es la copia del Shipment.label correspondiente, si se especifica en Shipment.
visitLabel

string

Es la copia del VisitRequest.label correspondiente, si se especifica en VisitRequest.

Transición

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

Si el vehículo no tiene un startLocation o un 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)

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

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 de tráfico para un Transition, este valor booleano se establece en verdadero. Esto puede ser temporal (un error 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 demora aplicadas a esta transición. Si hay alguna, la demora comienza exactamente delayDuration segundos antes del siguiente 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)

Es la suma de la duración de las pausas que se producen durante esta transición, si corresponde. Los detalles sobre la hora de inicio y la duración de cada pausa 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)

Es el tiempo que se pasó esperando durante esta transición. La duración de la espera corresponde al tiempo inactivo y no incluye el tiempo de descanso. Además, ten en cuenta que este tiempo de espera puede dividirse 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 esta 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.

Una marca de tiempo en formato RFC3339 UTC “Zulú”, con una resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z" y "2014-10-02T15:01:23.045123456Z".
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 está configurado 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 que se cambie la ruta, respetar la intención original cuando se creó la ruta. Trata este token como un blob opaco. No compares su valor entre las solicitudes, ya que puede cambiar incluso si el servicio muestra exactamente la misma ruta. Este campo solo se propaga si populateTransitionPolylines está configurado como verdadero.
vehicleLoads

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

Cargas de vehículos durante esta transición, para cada tipo que aparezca en el Vehicle.load_limits de este vehículo o que tenga 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, se agregan o se restan los loadDemands de la visita para obtener las cargas de la siguiente transición, según si la visita fue una recolección o una entrega.

EncodedPolyline

Es la representación codificada de una polilínea. Puedes obtener 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

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 una pausa.

Una marca de tiempo en formato RFC3339 UTC “Zulú”, con una resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z" y "2014-10-02T15:01:23.045123456Z".
duration

string (Duration format)

Es la duración de una pausa.

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