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 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 a ela (mesmo índice) e 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.

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 as VIAGENS, INTERVALOS, ATRASO e ESPERA podem ser organizadas 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

Veículo que executa a rota, identificado pelo índice na origem ShipmentModel.
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 uma rota. visits[i] é a i-ésima visita na rota. Se esse campo estiver vazio, o veículo será considerado como 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 mais tarde do que a janela de tempo atual devido ao aumento da estimativa de tempo de viagem 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 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 a custos. 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.

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,
  "injectedSolutionLocationToken": integer
}
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 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).

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 aos envios visitados na rota antes da visita e ao possível 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.
injectedSolutionLocationToken

integer

Um token opaco que representa informações sobre um local de visita.

Este campo pode ser preenchido nas visitas dos trajetos dos resultados quando VisitRequest.avoid_u_turns for definido como verdadeiro para essa visita ou se ShipmentModel.avoid_u_turns for definido como verdadeiro na solicitação OptimizeToursRequest.

Transição

Transição entre dois eventos na rota. Consulte 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 (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 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. 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á 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 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 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. 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 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".