ShipmentRoute

L'itinerario di un veicolo può essere scomposto, lungo l'asse temporale, in questo modo (supponiamo che ci siano n visite):

  |            |            |          |       |  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

Tieni presente che facciamo una distinzione tra:

  • "eventi puntuali", come l'inizio e la fine del viaggio del veicolo e l'inizio e la fine di ogni visita (ovvero l'arrivo e la partenza). Si verificano in un determinato secondo.
  • "intervalli di tempo", come le visite stesse e la transizione tra le visite. Sebbene gli intervalli di tempo possano a volte avere durata zero, ovvero iniziare e terminare nello stesso secondo, spesso hanno una durata positiva.

Invarianti:

  • Se ci sono n visite, ci sono n+1 transizioni.
  • Una visita è sempre preceduta da una transizione (stesso indice) e seguita da una transizione (indice + 1).
  • L'avvio del veicolo è sempre seguito dalla transizione n. 0.
  • La fine del veicolo è sempre preceduta dalla transizione n.

Ingrandendo, ecco cosa succede durante un Transition e un 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

Infine, ecco come possono essere organizzati gli spostamenti, le pause, i ritardi e le attese durante una transizione.

  • Non si sovrappongono.
  • Il RITARDO è univoco e deve essere un periodo di tempo contiguo immediatamente precedente alla visita successiva (o alla fine della corsa). Pertanto, è sufficiente conoscere la durata del ritardo per conoscerne l'ora di inizio e di fine.
  • Le PAUSE sono periodi di tempo contigui e non sovrapposti. La risposta specifica l'ora di inizio e la durata di ogni pausa.
  • TRAVEL e WAIT sono "preemptive": possono essere interrotti più volte durante questa transizione. I clienti possono presumere che il viaggio avvenga "il prima possibile" e che il "tempo di attesa" riempia il tempo rimanente.

Un esempio (complesso):

                               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     |       |           |         |         ||
  ||     |       |           |       |           |         |         ||
--++-----------------------------------------------------------------++-->
Rappresentazione 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
}
Campi
vehicleIndex

integer

Veicolo che esegue il percorso, identificato dal relativo indice nell'origine ShipmentModel.
vehicleLabel

string

Etichetta del veicolo che esegue questa route, uguale a ShipmentModel.vehicles(vehicleIndex).label, se specificata.
vehicleStartTime

string (Timestamp format)

Ora in cui il veicolo inizia il percorso.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
vehicleEndTime

string (Timestamp format)

Ora in cui il veicolo termina il percorso.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
visits[]

object (Visit)

Sequenza ordinata di visite che rappresentano un percorso. visits[i] è la i-esima visita del percorso. Se questo campo è vuoto, il veicolo viene considerato inutilizzato.
transitions[]

object (Transition)

Elenco ordinato delle transizioni per l'itinerario.
hasTrafficInfeasibilities

boolean

Quando OptimizeToursRequest.consider_road_traffic è impostato su true, questo campo indica che le incoerenze nei tempi di percorrenza dell'itinerario vengono previste utilizzando le stime della durata del viaggio basate sul traffico. Potrebbe non esserci tempo sufficiente per completare il viaggio con traffico aggiustato, i ritardi e le pause tra le visite, prima della prima visita o dopo l'ultima visita, soddisfacendo comunque le finestre temporali di visita e del veicolo. Ad esempio,

  startTime(previous_visit) + duration(previous_visit) +
  travelDuration(previous_visit, next_visit) > startTime(next_visit)

L'arrivo in next_visit avverrà probabilmente più tardi rispetto all'attuale finestra temporale a causa dell'aumento della stima del tempo di percorrenza travelDuration(previous_visit, next_visit) dovuto al traffico. Inoltre, una pausa potrebbe essere forzata a sovrapporsi a una visita a causa di un aumento delle stime del tempo di percorrenza e delle limitazioni delle finestre temporali di visita o pausa.
routePolyline

object (EncodedPolyline)

La rappresentazione della polilinea codificata del percorso. Questo campo viene compilato solo se il criterio OptimizeToursRequest.populate_polylines è impostato su true.
breaks[]

object (Break)

Pause programmate per il veicolo che esegue questo percorso. La sequenza breaks rappresenta intervalli di tempo, ognuno dei quali inizia al valore startTime corrispondente e dura duration secondi.
metrics

object (AggregatedMetrics)

Metriche di durata, distanza e carico per questo percorso. I campi di AggregatedMetrics vengono sommati per tutti i ShipmentRoute.transitions o ShipmentRoute.visits, a seconda del contesto.
vehicleFullness

object (VehicleFullness)

Campo VehicleFullness per calcolare quanto si avvicinano le metriche con limite ai rispettivi limiti del veicolo. I suoi campi sono i rapporti tra un campo di metrica con limite (ad es. AggregatedMetrics.travel_distance_meters) e il limite del veicolo correlato (ad es. Vehicle.route_distance_limit).

Sperimentale: il comportamento o l'esistenza di questo campo potrebbero cambiare in futuro.
routeCosts

map (key: string, value: number)

Costo dell'itinerario, suddiviso per campi della richiesta correlati al costo. Le chiavi sono i percorsi proto, relativi all'input OptimizeToursRequest, ad esempio "model.shipments.pickups.cost", e i valori sono il costo totale generato dal campo di costo corrispondente, aggregato sull'intero percorso. In altre parole, costs["model.shipments.pickups.cost"] è la somma di tutti i costi di ritiro lungo il percorso. Tutti i costi definiti nel modello sono riportati in dettaglio qui, ad eccezione dei costi relativi a TransitionAttributes che vengono riportati solo in modo aggregato a partire dal 01/01/2022.
routeTotalCost

number

Costo totale dell'itinerario. La somma di tutti i costi nella mappa dei costi.

Visita

Una visita eseguita durante un percorso. Questa visita corrisponde a un ritiro o a una consegna di un Shipment.

Rappresentazione JSON 
{
  "shipmentIndex": integer,
  "isPickup": boolean,
  "visitRequestIndex": integer,
  "startTime": string,
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "detour": string,
  "shipmentLabel": string,
  "visitLabel": string,
  "visitType": enum (VisitType),
  "injectedSolutionLocationToken": integer
}
Campi
shipmentIndex

integer

Indice del campo shipments nell'origine ShipmentModel.
isPickup

boolean

Se è true, la visita corrisponde al ritiro di un Shipment. In caso contrario, corrisponde a una consegna.
visitRequestIndex

integer

Indice di VisitRequest nel campo del ritiro o della consegna di Shipment (vedi isPickup).
startTime

string (Timestamp format)

Ora in cui inizia la visita. Tieni presente che il veicolo potrebbe arrivare prima di quest'ora nella posizione della visita. Gli orari sono coerenti con ShipmentModel.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
loadDemands

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

Domanda totale di carico delle visite come somma della spedizione e della richiesta di visita loadDemands. I valori sono negativi se la visita è una consegna. Le richieste vengono segnalate per gli stessi tipi di Transition.loads (vedi questo campo).
detour

string (Duration format)

Tempo di deviazione aggiuntivo dovuto alle spedizioni visitate sull'itinerario prima della visita e al potenziale tempo di attesa indotto dalle finestre temporali. Se la visita è una consegna, la deviazione viene calcolata dalla visita di ritiro corrispondente ed è uguale a:

startTime(delivery) - startTime(pickup)
- (duration(pickup) + travel duration from the pickup location
to the delivery location).

In caso contrario, viene calcolato dal veicolo startLocation ed è uguale a:

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

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".
shipmentLabel

string

Copia del Shipment.label corrispondente, se specificato in Shipment.
visitLabel

string

Copia del VisitRequest.label corrispondente, se specificato in VisitRequest.
visitType

enum (VisitType)

Facoltativo. Specifica il tipo di visita. Esegue l'override del campo Visit.is_pickup.
injectedSolutionLocationToken

integer

Un token opaco che rappresenta le informazioni su una posizione di visita.

Questo campo può essere compilato nelle visite degli itinerari dei risultati quando VisitRequest.avoid_u_turns è stato impostato su true per questa visita o se ShipmentModel.avoid_u_turns è stato impostato su true nella richiesta OptimizeToursRequest.

Sperimentale: per ulteriori dettagli, visita la pagina https://developers.google.com/maps/tt/route-optimization/experimental/u-turn-avoidance/make-request.

VisitType

Indica se la visita è un ritiro, una consegna o una visita a un Stop. Le visite a un Stop vengono utilizzate solo quando è attivata l'ottimizzazione multimodale.

Enum
VISIT_TYPE_UNSPECIFIED Tipo di visita non specificato.
PICKUP_SHIPMENT La visita corrisponde al ritiro di una spedizione.
DELIVER_SHIPMENT La visita corrisponde a una consegna della spedizione.

Transizione

Transizione tra due eventi sul percorso. Consulta la descrizione di ShipmentRoute.

Se il veicolo non dispone di startLocation e/o endLocation, le metriche di viaggio corrispondenti sono pari a 0.

Rappresentazione 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)
    },
    ...
  }
}
Campi
travelDuration

string (Duration format)

Durata del viaggio durante questa transizione.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".
travelDistanceMeters

number

Distanza percorsa durante la transizione.
trafficInfoUnavailable

boolean

Quando il traffico viene richiesto tramite OptimizeToursRequest.consider_road_traffic e le informazioni sul traffico non possono essere recuperate per un Transition, questo valore booleano è impostato su true. Potrebbe trattarsi di un problema temporaneo (un raro problema nei server del traffico in tempo reale) o permanente (nessun dato per questa posizione).
delayDuration

string (Duration format)

Somma delle durate del ritardo applicate a questa transizione. Se presente, il ritardo inizia esattamente delayDuration secondi prima dell'evento successivo (visita o fine del viaggio). Leggi i TransitionAttributes.delay.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".
breakDuration

string (Duration format)

Somma della durata delle pause che si verificano durante questa transizione, se presenti. I dettagli sull'ora di inizio e sulla durata di ogni pausa sono memorizzati in ShipmentRoute.breaks.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".
waitDuration

string (Duration format)

Tempo trascorso in attesa durante questa transizione. La durata dell'attesa corrisponde al tempo di inattività e non include il tempo di pausa. Tieni inoltre presente che questo tempo di attesa potrebbe essere suddiviso in diversi intervalli non contigui.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".
totalDuration

string (Duration format)

Durata totale della transizione, fornita per comodità. È uguale a:

  • visita successiva startTime (o vehicleEndTime se si tratta dell'ultima transizione) - startTime di questa transizione;
  • se ShipmentRoute.has_traffic_infeasibilities è false, vale anche quanto segue: `totalDuration = travelDuration + delayDuration
  • breakDuration + waitDuration`.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".
startTime

string (Timestamp format)

Ora di inizio di questa transizione.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
routePolyline

object (EncodedPolyline)

La rappresentazione della polilinea codificata del percorso seguito durante la transizione. Questo campo viene compilato solo se il criterio populateTransitionPolylines è impostato su true.
routeToken

string

Solo output. Un token opaco che può essere passato all'SDK Navigation per ricostruire l'itinerario durante la navigazione e, in caso di ricalcolo, rispettare l'intenzione originale al momento della creazione dell'itinerario. Considera questo token come un blob opaco. Non confrontare il suo valore tra le richieste, in quanto potrebbe cambiare anche se il servizio restituisce esattamente lo stesso percorso. Questo campo viene compilato solo se il criterio populateTransitionPolylines è impostato su true.
vehicleLoads

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

Carichi del veicolo durante questa transizione, per ogni tipo che compare nel Vehicle.load_limits di questo veicolo o che ha un Shipment.load_demands diverso da zero in alcune spedizioni eseguite su questa tratta.

I carichi durante la prima transizione sono i carichi iniziali dell'itinerario del veicolo. Poi, dopo ogni visita, i loadDemands della visita vengono aggiunti o sottratti per ottenere i carichi della transizione successiva, a seconda che la visita sia stata un ritiro o una consegna.

EncodedPolyline

La rappresentazione codificata di una polilinea. Per ulteriori informazioni sulla codifica polilineare, visita le pagine https://developers.google.com/maps/documentation/utilities/polylinealgorithm e https://developers.google.com/maps/documentation/javascript/reference/geometry#encoding.

Rappresentazione JSON 
{
  "points": string
}
Campi
points

string

Stringa che rappresenta i punti codificati della polilinea.

Pausa

Dati che rappresentano l'esecuzione di una pausa.

Rappresentazione JSON 
{
  "startTime": string,
  "duration": string
}
Campi
startTime

string (Timestamp format)

Ora di inizio di una pausa.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
duration

string (Duration format)

Durata di una pausa.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".

VehicleFullness

VehicleFullness è una metrica che calcola il livello di riempimento di un veicolo. Ogni campo VehicleFullness è compreso tra 0 e 1 e viene calcolato come rapporto tra un campo metrico con limite (ad es. AggregatedMetrics.travel_distance_meters) e il relativo limite del veicolo (ad es. Vehicle.route_distance_limit), se esistente. In caso contrario, il rapporto di riempimento rimane non impostato. Se il limite è 0, il campo è impostato su 1. Nota: quando un percorso è soggetto a problemi di traffico, alcuni rapporti di riempimento grezzi potrebbero superare 1,0, ad esempio il veicolo potrebbe superare il limite di distanza. In questi casi, i valori di riempimento vengono limitati a 1,0.

Rappresentazione JSON 
{
  "maxFullness": number,
  "distance": number,
  "travelDuration": number,
  "activeDuration": number,
  "maxLoad": number,
  "activeSpan": number
}
Campi
maxFullness

number

Il valore massimo di tutti gli altri campi di questo messaggio.
distance

number

Il rapporto tra AggregatedMetrics.travel_distance_meters e Vehicle.route_distance_limit. Se Vehicle.route_distance_limit non è impostato, questo campo non verrà impostato.
travelDuration

number

Il rapporto tra [AggregatedMetrics.travel_duration_seconds][] e Vehicle.travel_duration_limit. Se Vehicle.travel_duration_limit non è impostato, questo campo non verrà impostato.
activeDuration

number

Il rapporto tra [AggregatedMetrics.total_duration_seconds][] e Vehicle.route_duration_limit. Se Vehicle.route_duration_limit non è impostato, questo campo non verrà impostato.
maxLoad

number

Il rapporto massimo tra tutti i tipi di [AggregatedMetrics.max_load][] e i rispettivi Vehicle.load_limits. Se tutti i campi Vehicle.load_limits non sono impostati, questo campo non verrà impostato.
activeSpan

number

Il rapporto (vehicleEndTime - vehicleStartTime) / (latestVehicleEndTime - earliestVehicleStartTime) per un determinato veicolo. Se il denominatore non è presente, viene utilizzato (ShipmentModel.global_end_time - ShipmentModel.global_start_time).