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 diferencia entre lo siguiente:

  • "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 las visitas. Si bien los intervalos de tiempo a veces pueden tener una duración de cero, es decir, comienzan y terminan 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 de una transición anterior (mismo índice) y una transición posterior (índice + 1).
  • El inicio del vehículo siempre va seguido de la transición #0.
  • El final del vehículo siempre está precedido por la transición n.

Acerca la imagen. Esto es lo que sucede durante una Transition y una 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.
  • La demora es única y debe ser un período contiguo justo antes de la próxima visita (o la finalización del vehículo). Por lo tanto, es suficiente conocer la duración del retraso para conocer la hora de inicio y finalización.
  • Las PAUSAS son períodos de tiempo contiguos y no superpuestos. La respuesta especifica la hora de inicio y la duración de cada pausa.
  • 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)
  },
  "routeCosts": {
    string: number,
    ...
  },
  "routeTotalCost": number
}
Campos
vehicleIndex

integer

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

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 finaliza 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, se considerará que el vehículo no está en uso.

transitions[]

object (Transition)

Es la lista ordenada de transiciones de la ruta.

hasTrafficInfeasibilities

boolean

Cuando la opción OptimizeToursRequest.consider_road_traffic se establece como verdadera, este campo indica que las inconsistencias en los horarios de la ruta se predicen mediante estimaciones de duración de viaje basadas en el tráfico. Es posible que no haya suficiente tiempo para completar los viajes, las demoras y las pausas ajustadas por el tráfico entre las visitas, antes o después de la última visita, sin dejar de cumplir con los horarios de la 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 ocurra después de su período 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 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 se establece OptimizeToursRequest.populate_polylines 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

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

Índice del campo shipments en la fuente ShipmentModel.

isPickup

boolean

Si es verdadero, la visita corresponde al retiro 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 corresponde a una entrega a domicilio. 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 corresponde a una entrega a domicilio, 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 tráfico a través de OptimizeToursRequest.consider_road_traffic y la información sobre el tráfico no se pudo recuperar para un Transition, este valor booleano se establece como 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 retraso aplicadas a esta transición. Si hubiera alguno, el retraso comienza exactamente delayDuration segundos antes del próximo evento (finalización de la visita o el 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 las pausas que ocurren durante esta transición, si las hubiera. 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)

Tiempo de espera 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, proporcionada 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 aplica lo siguiente: "totalDuration = journeyDuration + lateDuration
  • "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)

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 redireccione, 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 su valor 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 próxima transición, dependiendo de si la visita fue un retiro o una entrega.

EncodedPolyline

Es la representación codificada de una polilínea. Para obtener más información sobre la codificación de polilíneas, consulta la siguiente información: 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.

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