ShipmentRoute

A rota de um veículo pode ser decomposta, ao longo do eixo do tempo, desta forma (assumimos 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, 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.
  • 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 "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

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

string

Rótulo do veículo que executa essa rota, 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 é 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 as viagens ajustadas ao tráfego, os atrasos e os intervalos entre as visitas, antes da primeira visita ou depois da última visita, sem deixar de atender às janelas de tempo de 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 estiver definido como verdadeiro.
breaks[]

object (Break)

Pausas programadas para o veículo que faz essa rota. 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 ao longo de todo o trajeto. 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 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 à retirada de um 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 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 do 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 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 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. Consulte a descrição de ShipmentRoute.

Se o veículo não tiver 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 as informações de trânsito não podem ser recuperadas para um Transition, esse booleano é definido como verdadeiro. Isso pode ser temporário (problema raro nos servidores de trânsito em tempo real) ou permanente (nenhum dado para esse 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 a hora de início e a duração de cada intervalo são armazenados em 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 esperando durante essa transição. A duração da espera corresponde ao tempo de inatividade e não inclui o tempo de intervalo. Além disso, 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 for a última transição) startTime da 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 desta 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))

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

EncodedPolyline

A representação codificada de uma polilinha. Confira mais informações sobre a codificação de polilinha em: 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".