ShipmentRoute

O trajeto de um veículo pode ser decomposto ao longo do eixo de tempo, da seguinte forma (consideramos que há 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

Observe que fazemos uma diferença entre:

  • "eventos pontuais", como o início e o término do veículo e o início e fim de cada visita (também conhecido como chegada e partida). Acontecem em um determinado segundo.
  • "intervalos de tempo", como as próprias visitas e a transição entre as visitas. Embora os intervalos às vezes possam ter duração zero, ou seja, começam e terminam no mesmo segundo, eles geralmente têm uma duração positiva.

Invariantes:

  • Se houver n visitas, haverá n+1 transições.
  • Uma visita é sempre cercada por uma transição antes dela (mesmo índice) e por uma transição depois dela (índice + 1).
  • A partida do veículo é sempre seguida pela transição 0.
  • O fim do veículo é sempre precedido pela transição #n.

Ao aumentar o zoom, veja o que acontece durante uma Transition e uma 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 fim, veja como VIAGENS, QUEBRAS, ATRASO e ESPERA podem ser organizadas durante uma transição.

  • Eles não se sobrepõem.
  • O atraso é exclusivo e precisa ser um período contíguo antes da próxima visita (ou do fim do veículo). Portanto, é suficiente conhecer a duração do atraso para saber os horários de início e término.
  • As BREAKS são períodos contíguos e não sobrepostos. A resposta especifica o horário de início e a duração de cada intervalo.
  • VIAGENS e ESPERA são "preveníveis": elas podem ser interrompidas várias vezes durante essa transição. Os clientes podem presumir que a viagem acontece "o mais rápido possível" e que "espera" preenche o tempo restante.

Um exemplo (complexo):

                               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     |       |           |         |         ||
  ||     |       |           |       |           |         |         ||
--++-----------------------------------------------------------------++-->
Representação 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

Veículo que realiza o trajeto, identificado pelo índice na origem ShipmentModel.
vehicleLabel

string

Etiqueta do veículo que faz este trajeto, igual a ShipmentModel.vehicles(vehicleIndex).label, se especificado.
vehicleStartTime

string (Timestamp format)

Horário em que o veículo inicia seu trajeto.

Um carimbo de data/hora no formato UTC "Zulu" RFC3339, com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
vehicleEndTime

string (Timestamp format)

Horário em que o veículo termina seu trajeto.

Um carimbo de data/hora no formato UTC "Zulu" RFC3339, com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
visits[]

object (Visit)

Sequência ordenada de visitas que representam um trajeto. Visitas [i] é a i-ésima visita no trajeto. Se este campo estiver vazio, o veículo será considerado não utilizado.
transitions[]

object (Transition)

Lista ordenada de transições para a rota.
hasTrafficInfeasibilities

boolean

Quando OptimizeToursRequest.consider_road_traffic é definido como verdadeiro, esse campo indica que as inconsistências nos horários do trajeto são previstas usando estimativas de duração do trajeto com base no trânsito. Talvez não haja tempo suficiente para concluir viagens, atrasos e intervalos ajustados ao trânsito entre as visitas, antes da primeira visita ou depois da última, mas ainda atender às janelas de tempo da visita e do veículo. Por exemplo:

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

A chegada em next_visit provavelmente acontecerá depois do período atual devido à estimativa elevada do tempo de viagem travelDuration(previous_visit, next_visit) devido ao trânsito. Além disso, uma pausa pode se sobrepor a uma visita devido a um aumento nas estimativas de tempo de viagem e restrições das janelas de tempo de visita ou intervalo.
routePolyline

object (EncodedPolyline)

A representação de polilinha codificada do trajeto. Esse campo só será preenchido se OptimizeToursRequest.populate_polylines estiver definido como verdadeiro.
breaks[]

object (Break)

Pausas programadas para o veículo que está executando este trajeto. A sequência breaks representa intervalos de tempo, cada um começando no startTime correspondente e durando duration segundos.
metrics

object (AggregatedMetrics)

Métricas de duração, distância e carregamento para este trajeto. Os campos de AggregatedMetrics são somados em todos os ShipmentRoute.transitions ou ShipmentRoute.visits, dependendo do contexto.
routeCosts

map (key: string, value: number)

Custo do trajeto detalhado por campos de solicitação relacionados ao custo. As chaves são caminhos proto em relação à entrada OptimizeToursRequest, por exemplo, "model.shipments.pickups.cost", e os valores são o custo total gerado pelo campo de custo correspondente, agregado em todo o trajeto. Em outras palavras, os custos["model.shipments.pickups.cost"] são a soma de todos os custos de embarque no trajeto. Todos os custos definidos no modelo são informados em detalhes aqui, com exceção dos custos relacionados a TransitionAttributes que só são informados de forma agregada a partir de 2022/01.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
routeTotalCost

number

Custo total do trajeto. A soma de todos os custos no mapa de custos.

Acessar

Uma visita realizada durante um trajeto. Essa visita corresponde à retirada ou entrega de um Shipment.

Representação JSON 
{
  "shipmentIndex": integer,
  "isPickup": boolean,
  "visitRequestIndex": integer,
  "startTime": string,
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "detour": string,
  "shipmentLabel": string,
  "visitLabel": string
}
Campos
shipmentIndex

integer

Índice do campo shipments na origem ShipmentModel.
isPickup

boolean

Se verdadeiro, a visita corresponde ao embarque de um Shipment. Caso contrário, ele corresponde a uma entrega.
visitRequestIndex

integer

Índice de VisitRequest no campo de retirada ou entrega de Shipment (consulte isPickup).
startTime

string (Timestamp format)

Horário em que a visita começa. O veículo pode chegar antes desse horário no local da visita. Os horários são consistentes com o ShipmentModel.

Um carimbo de data/hora no formato UTC "Zulu" RFC3339, com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
loadDemands

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

Demanda total de carga da visita como a soma do frete e da solicitação de visita loadDemands. Os valores serão negativos se a visita for uma entrega. As demandas são informadas para os mesmos tipos que Transition.loads (consulte este campo).

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
detour

string (Duration format)

Tempo de desvio extra devido às encomendas visitadas no trajeto antes da visita e ao tempo de espera em potencial induzido pelas janelas de tempo. Se a visita for uma entrega, o desvio será calculado a partir da visita de retirada correspondente e será igual a:

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

Caso contrário, ele será calculado a partir do startLocation do veículo e será igual a:

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

Uma duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".
shipmentLabel

string

Cópia do Shipment.label correspondente, se especificado no Shipment.
visitLabel

string

Cópia do VisitRequest.label correspondente, se especificado no VisitRequest.

Transição

Transição entre dois eventos no trajeto. Veja a descrição de ShipmentRoute.

Se o veículo não tiver um startLocation e/ou endLocation, as métricas de viagem correspondentes serão 0.

Representação JSON 
{
  "travelDuration": string,
  "travelDistanceMeters": number,
  "trafficInfoUnavailable": boolean,
  "delayDuration": string,
  "breakDuration": string,
  "waitDuration": string,
  "totalDuration": string,
  "startTime": string,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "vehicleLoads": {
    string: {
      object (VehicleLoad)
    },
    ...
  }
}
Campos
travelDuration

string (Duration format)

Duração da viagem durante essa transição.

Uma duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".
travelDistanceMeters

number

Distância percorrida durante a transição.
trafficInfoUnavailable

boolean

Quando o tráfego é solicitado pelo OptimizeToursRequest.consider_road_traffic e não é possível recuperar as informações de trânsito para um Transition, esse booleano é definido como "true". Isso pode ser temporário (erro raro nos servidores de tráfego em tempo real) ou permanente (sem dados para este local).
delayDuration

string (Duration format)

Soma das durações de atraso aplicadas a essa transição. Se for o caso, o atraso começará exatamente delayDuration segundos antes do próximo evento (visita ou fim do veículo). Consulte os TransitionAttributes.delay.

Uma duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".
breakDuration

string (Duration format)

Soma da duração das pausas que ocorrem durante essa transição, se houver. Os detalhes sobre o horário de início e a duração de cada intervalo são armazenados em ShipmentRoute.breaks.

Uma duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".
waitDuration

string (Duration format)

Tempo gasto esperando durante a transição. A duração da espera corresponde ao tempo de inatividade e não inclui o intervalo. Além disso, esse tempo de espera pode ser dividido em vários intervalos não contíguos.

Uma duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".
totalDuration

string (Duration format)

Duração total da transição, fornecida por conveniência. Ele é igual a:

  • Próxima visita startTime (ou vehicleEndTime, se esta for a última transição): o startTime dessa transição.
  • Se ShipmentRoute.has_traffic_infeasibilities for falso, o seguinte também será válido: "totalDuration = TravelDuration + delayDuration"
  • breakDuration + WaitDuration`.

Uma duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".
startTime

string (Timestamp format)

Horário de início dessa transição.

Um carimbo de data/hora no formato UTC "Zulu" RFC3339, com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
routePolyline

object (EncodedPolyline)

A representação de polilinha codificada do trajeto seguido durante a transição. Esse campo só será preenchido se populateTransitionPolylines estiver definido como verdadeiro.
vehicleLoads

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

Cargas de veículos durante essa transição, para cada tipo que aparece no Vehicle.load_limits do veículo ou que têm um Shipment.load_demands diferente de zero em algumas remessas realizadas neste trajeto.

As cargas durante a primeira transição são as cargas iniciais do trajeto do veículo. Após cada visita, os loadDemands são adicionados ou subtraídos para gerar as cargas da próxima transição, dependendo se a visita foi de retirada ou entrega.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

EncodedPolyline

A representação codificada de uma polilinha. Mais informações sobre codificação de polilinhas podem ser encontradas aqui: https://developers.google.com/maps/documentation/utilities/polylinealgorithm https://developers.google.com/maps/documentation/javascript/reference/geometry#encoding.

Representação JSON 
{
  "points": string
}
Campos
points

string

String que representa pontos codificados da polilinha.

Intervalo

Dados que representam a execução de uma pausa.

Representação JSON 
{
  "startTime": string,
  "duration": string
}
Campos
startTime

string (Timestamp format)

Horário de início de uma pausa.

Um carimbo de data/hora no formato UTC "Zulu" RFC3339, com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
duration

string (Duration format)

Duração de uma pausa.

Uma duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".