ShipmentRoute

A rota de um veículo pode ser decomposta ao longo do eixo de tempo da seguinte maneira (supondo que haja 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

Observação: fazemos uma distinção 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, chegada e partida). Elas 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 possam ter duração zero, ou seja, começar e terminar 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 (mesmo índice) e uma transição depois (índice + 1).
  • O início do veículo é sempre seguido pela transição nº 0.
  • O fim do veículo é sempre precedido pela transição nº n.

Confira o que acontece durante um Transition e um 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 TRAVEL, BREAKS, DELAY e WAIT podem ser organizados durante uma transição.

  • Elas não se sobrepõem.
  • O DELAY é exclusivo e precisa ser um período contínuo imediatamente antes da próxima visita (ou do fim da viagem do veículo). Assim, basta saber a duração do atraso para saber o horário de início e término.
  • Os 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 "preemptable": podem ser interrompidos várias vezes durante essa transição. Os clientes podem presumir que a viagem acontece "assim que possível" e que "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)
  },
  "vehicleFullness": {
    object (VehicleFullness)
  },
  "routeCosts": {
    string: number,
    ...
  },
  "routeTotalCost": number
}
Campos
vehicleIndex

integer

Veículo que está fazendo o trajeto, identificado pelo índice na ShipmentModel de origem.
vehicleLabel

string

Rótulo do veículo que está fazendo essa rota, igual a ShipmentModel.vehicles(vehicleIndex).label, se especificado.
vehicleStartTime

string (Timestamp format)

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

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
vehicleEndTime

string (Timestamp format)

Hora em que o veículo termina o trajeto.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
visits[]

object (Visit)

Sequência ordenada de visitas que representam um trajeto. "visits[i]" é a i-ésima visita no trajeto. 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 "true", esse campo indica que as inconsistências nos horários das rotas são previstas usando estimativas de duração da viagem com base no trânsito. Pode não haver tempo suficiente para concluir a viagem ajustada ao trânsito, atrasos e pausas entre as visitas, antes da primeira visita ou depois da última, sem violar as 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 mais tarde do que a janela de tempo atual devido ao aumento da estimativa de tempo de viagem travelDuration(previous_visit, next_visit) por causa do trânsito. Além disso, uma pausa pode ser forçada a se sobrepor a uma visita devido a um aumento nas estimativas de tempo de viagem e restrições de janela de tempo de visita ou pausa.
routePolyline

object (EncodedPolyline)

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

object (Break)

Intervalos programados para o veículo que está fazendo esse 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.
vehicleFullness

object (VehicleFullness)

Campo VehicleFullness para calcular a proximidade das métricas limitadas aos respectivos limites de veículos. Os campos são proporções entre um campo de métricas limitado (por exemplo, AggregatedMetrics.travel_distance_meters) e o limite relacionado do veículo (por exemplo, Vehicle.route_distance_limit).

Experimental: o comportamento ou a existência deste campo podem mudar no futuro.
routeCosts

map (key: string, value: number)

Custo do trajeto, detalhado por campos de solicitação relacionados a custos. As chaves são caminhos de proto, relativos ao OptimizeToursRequest de entrada, 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 coleta ao longo do trajeto. Todos os custos definidos no modelo são informados em detalhes aqui, exceto os custos relacionados a "TransitionAttributes", que são informados apenas de forma agregada a partir de 01/2022.
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 a uma 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,
  "injectedSolutionLocationToken": integer
}
Campos
shipmentIndex

integer

Índice do campo shipments no ShipmentModel de origem.
isPickup

boolean

Se for verdadeiro, a visita vai corresponder a uma 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 desse horário no local da visita. Os horários são consistentes com o ShipmentModel.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
loadDemands

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

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

string (Duration format)

Tempo extra de desvio devido às entregas visitadas 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 com base na visita de coleta 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 com base no startLocation do veículo 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.

Esse campo pode ser preenchido nas visitas das rotas de resultado quando VisitRequest.avoid_u_turns foi definido como verdadeiro para essa visita ou se ShipmentModel.avoid_u_turns foi definido como verdadeiro na solicitação OptimizeToursRequest.

Experimental: consulte https://developers.google.com/maps/tt/route-optimization/experimental/u-turn-avoidance/make-request para mais detalhes.

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)
  },
  "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 via 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 (um problema raro nos servidores de trânsito em tempo real) ou permanente (não há dados 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 fim da viagem). 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 dos intervalos 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.

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 ocioso 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ínuos.

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 for a última transição) - startTime desta transição;
  • Se ShipmentRoute.has_traffic_infeasibilities for "false", o seguinte também será válido: "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.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
routePolyline

object (EncodedPolyline)

A representação da polilinha codificada do trajeto seguido durante a transição. Esse campo só será preenchido se populateTransitionPolylines estiver definido como "true".
routeToken

string

Apenas saída. Um token opaco que pode ser transmitido ao SDK Navigation para reconstruir o trajeto durante a navegação e, em caso de novo trajeto, respeitar a intenção original quando o trajeto foi criado. Trate esse token como um blob opaco. Não compare o valor dele em várias 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 "true".
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 tem Shipment.load_demands diferente de zero em algum frete realizado nessa rota.

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

EncodedPolyline

A representação codificada de uma polilinha. Saiba mais sobre a codificação de polilinhas: 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 interrupção.

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

string (Timestamp format)

Horário de início de um intervalo.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
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".

VehicleFullness

VehicleFullness é uma métrica que calcula o nível de ocupação de um veículo. Cada campo VehicleFullness está entre 0 e 1, calculado como a proporção entre um campo de métrica limitado (por exemplo, AggregatedMetrics.travel_distance_meters) e o limite de veículo relacionado (por exemplo, Vehicle.route_distance_limit), se existir. Caso contrário, a proporção de plenitude não será definida. Se o limite for 0, o campo será definido como 1. Observação: quando uma rota está sujeita a inviabilidades de trânsito, algumas proporções de ocupação bruta podem exceder 1,0. Por exemplo, o veículo pode exceder o limite de distância. Nesses casos, limitamos os valores de plenitude a 1,0.

Representação JSON 
{
  "maxFullness": number,
  "distance": number,
  "travelDuration": number,
  "activeDuration": number,
  "maxLoad": number,
  "activeSpan": number
}
Campos
maxFullness

number

Máximo de todos os outros campos nesta mensagem.
distance

number

A proporção entre AggregatedMetrics.travel_distance_meters e Vehicle.route_distance_limit. Se Vehicle.route_distance_limit não estiver definido, este campo também não estará.
travelDuration

number

A proporção entre [AggregatedMetrics.travel_duration_seconds][] e Vehicle.travel_duration_limit. Se Vehicle.travel_duration_limit não estiver definido, este campo também não estará.
activeDuration

number

A proporção entre [AggregatedMetrics.total_duration_seconds][] e Vehicle.route_duration_limit. Se Vehicle.route_duration_limit não estiver definido, este campo também não estará.
maxLoad

number

A proporção máxima entre todos os tipos de [AggregatedMetrics.max_load][] e os respectivos Vehicle.load_limits. Se todos os campos Vehicle.load_limits não estiverem definidos, este campo também não estará.
activeSpan

number

A proporção (vehicleEndTime - vehicleStartTime) / (latestVehicleEndTime - earliestVehicleStartTime) para um determinado veículo. Se o denominador não estiver presente, ele usará (ShipmentModel.global_end_time - ShipmentModel.global_start_time).