ShipmentRoute

O trajeto de um veículo pode ser decomposto ao longo do eixo de tempo, desta 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 início e fim do veículo e o início e o término de cada visita (também conhecido como chegada e partida). Eles acontecem em um determinado segundo.
  • "intervalos de tempo", como as próprias visitas e a transição entre as visitas. Embora os intervalos de tempo à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 anterior a ela (mesmo índice) e uma transição depois dela (índice + 1).
  • O início do veículo é sempre seguido pela transição 0.
  • O fim do veículo é sempre precedido pela transição #n.

Aumentando o zoom, confira 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 as VIAGENS, INTERVALOS, ATRASO e ESPERA podem ser organizadas durante uma transição.

  • Elas não se sobrepõem.
  • O atraso é único e precisa ser um período contíguo antes da próxima visita (ou do fim do veículo). Assim, basta saber a duração do atraso para saber o horário de início e de término.
  • As INTERVALOS 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.
  • VIAGEM e ESPERA são "preemptíveis": podem ser interrompidas várias vezes durante essa transição. Os clientes podem supor que a viagem acontece "assim que possível" e "esperar" 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

O veículo que faz o trajeto, identificado pelo índice na ShipmentModel de origem.
vehicleLabel

string

Rótulo do veículo que realiza esse trajeto, igual a ShipmentModel.vehicles(vehicleIndex).label, se especificado.
vehicleStartTime

string (Timestamp format)

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

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", 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 o trajeto.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", 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 for definido como verdadeiro, esse campo indica que as inconsistências nos tempos do trajeto são previstas usando estimativas de duração de viagem com base no tráfego. Talvez não haja tempo suficiente para concluir viagens ajustadas para o trânsito, atrasos e intervalos entre as visitas, antes da primeira ou depois da última visita e, ao mesmo tempo, 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 vai acontecer depois da janela de tempo atual devido ao aumento da estimativa do tempo de viagem de travelDuration(previous_visit, next_visit) devido ao trânsito. Além disso, um intervalo pode ser forçado a se sobrepor a uma visita devido a um aumento nas estimativas de tempo de viagem e às restrições da janela de tempo da visita ou do intervalo.
routePolyline

object (EncodedPolyline)

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

object (Break)

Intervalos programados para o veículo que executa 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 da rota, detalhado por campos de solicitação relacionados ao custo. As chaves são caminhos proto, relativos à 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, custos["model.shipments.pickups.cost"] é a soma de todos os custos de retirada no trajeto. Todos os custos definidos no modelo são informados em detalhes aqui, com exceção dos custos relacionados a TransitionAttributes que só foram informados de maneira 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.

Acesse

Uma visita realizada durante um trajeto. Essa visita corresponde a uma retirada ou entrega de 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 a um embarque de Shipment. Caso contrário, corresponde a uma entrega.
visitRequestIndex

integer

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

string (Timestamp format)

Horário em que a visita começa. O veículo pode chegar antes disso no local da visita. Os horários estão de acordo com ShipmentModel.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", 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 de carregamento total de visitas como a soma do envio 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 de 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 extra de desvio devido às remessas visitadas no trajeto antes da visita e ao potencial tempo de espera induzido pelas janelas de tempo. Se a visita for uma entrega, o desvio será calculado a partir da visita de embarque 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 veículo startLocation e será igual a:

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

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 na rota. 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.

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 por OptimizeToursRequest.consider_road_traffic e não é possível recuperar as informações de tráfego 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 (não há 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 vai começar exatamente delayDuration segundos antes do próximo evento (fim da visita ou do veículo). Consulte os TransitionAttributes.delay.

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 no ShipmentRoute.breaks.

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

string (Duration format)

Tempo gasto em espera durante essa transição. A duração da espera corresponde ao tempo de inatividade e não inclui o intervalo. Esse tempo de espera pode ser dividido em vários intervalos não contíguos.

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, indicada para conveniência. É igual a:

  • Próxima visita: startTime (ou vehicleEndTime se esta for a última transição): o startTime desta transição;
  • se ShipmentRoute.has_traffic_infeasibilities for falso, o seguinte também será mantido: `totalDuration = TravelDuration + delayDuration
  • breakDuration + waitDuration`.

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 RFC3339 UTC "Zulu", 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 que foi seguida durante a transição. Esse campo só será preenchido se populateTransitionPolylines for definido como verdadeiro.
vehicleLoads

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

Carregamentos de veículos durante essa transição, para cada tipo que aparece no Vehicle.load_limits do veículo ou que têm Shipment.load_demands diferente de zero em algum frete realizado nesse trajeto.

As cargas durante a primeira transição são as cargas iniciais do trajeto do veículo. Em seguida, após cada visita, os loadDemands da visita são adicionados ou subtraídos para receber as cargas da próxima transição, dependendo se a visita foi 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. Veja mais informações sobre a codificação de polilinhas 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)

Início do intervalo.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", 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.

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