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 o início e o fim do veículo e o início e o fim de cada visita (ou seja, a chegada e a partida). Eles acontecem em um determinado segundo.
  • "intervalos de tempo", como as visitas em si e a transição entre elas. Embora os intervalos de tempo às vezes tenham 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 (mesmo índice) e uma transição posterior (índice + 1).
  • A partida do veículo é sempre seguida 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, confira como TRAVEL, BREAKS, DELAY e WAIT podem ser organizados durante uma transição.

  • Elas não se sobrepõem.
  • O DELAY é único e precisa ser um período contíguo de tempo antes da próxima visita (ou término do veículo). Portanto, basta saber a duração do atraso para saber o início e o fim.
  • 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.
  • TRAVEL e WAIT são "preemptáveis": eles podem ser interrompidos várias vezes durante essa transição. Os clientes podem presumir que a viagem vai acontecer "assim que possível" e que o tempo restante será preenchido com "espera".

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)

Hora 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 é definido como verdadeiro, esse campo indica que as inconsistências nos horários da rota são previstas usando estimativas de duração da viagem com base no trânsito. 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 deslocamento e restrições de intervalo de tempo de visita ou 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 carga para essa rota. 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 OptimizeToursRequests, por exemplo, "model.shipments.pickups.cost", e os valores são o custo total gerado pelo campo de custo correspondente, agregado em toda a rota. Em outras palavras, costs["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.
routeTotalCost

number

Custo total da rota. A soma de todos os custos no mapa de custos.

Acesse

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 a um embarque de Shipment. Caso contrário, ele 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 ao local da visita. Os horários são consistentes com o 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 total de carga 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).
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 é calculado com base no startLocation do veículo e é 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)
  },
  "routeToken": string,
  "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 houver, o atraso começa exatamente delayDuration segundos antes do próximo evento (visita ou término 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 ocorridas 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 a transição. A duração da espera corresponde ao tempo de inatividade e não inclui o tempo de 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, fornecida 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á verdadeiro: "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 codificada da polilinha da rota seguida durante a transição. Esse campo só será preenchido se populateTransitionPolylines for definido como verdadeiro.
routeToken

string

Apenas saída. Um token opaco que pode ser transmitido ao SDK Navigation para reconstruir a rota durante a navegação e, em caso de redirecionamento, respeitar a intenção original quando a rota foi criada. Tratar esse token como um blob opaco. Não compare o valor dele entre solicitações, porque ele pode mudar mesmo que o serviço retorne exatamente a mesma rota. 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 na Vehicle.load_limits do veículo ou que tem Shipment.load_demands diferente de zero em algum envio realizado nessa rota.

As cargas durante a primeira transição são as cargas iniciais da rota do veículo. Depois, após cada visita, o loadDemands dela é adicionado ou subtraído para receber as cargas da próxima transição, dependendo se a visita foi uma retirada ou uma entrega.

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