ShipmentRoute

A vehicle's route can be decomposed, along the time axis, like this (we assume there are n visits):

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

Note that we make a difference between:

  • "punctual events", such as the vehicle start and end and each visit's start and end (aka arrival and departure). They happen at a given second.
  • "time intervals", such as the visits themselves, and the transition between visits. Though time intervals can sometimes have zero duration, i.e. start and end at the same second, they often have a positive duration.

Invariants:

  • If there are n visits, there are n+1 transitions.
  • A visit is always surrounded by a transition before it (same index) and a transition after it (index + 1).
  • The vehicle start is always followed by transition #0.
  • The vehicle end is always preceded by transition #n.

Zooming in, here is what happens during a Transition and a 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

Lastly, here is how the TRAVEL, BREAKS, DELAY and WAIT can be arranged during a transition.

  • They don't overlap.
  • The DELAY is unique and must be a contiguous period of time right before the next visit (or vehicle end). Thus, it suffice to know the delay duration to know its start and end time.
  • The BREAKS are contiguous, non-overlapping periods of time. The response specifies the start time and duration of each break.
  • TRAVEL and WAIT are "preemptable": they can be interrupted several times during this transition. Clients can assume that travel happens "as soon as possible" and that "wait" fills the remaining time.

A (complex) example:

                               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     |       |           |         |         ||
  ||     |       |           |       |           |         |         ||
--++-----------------------------------------------------------------++-->
JSON representation 
{
  "vehicleIndex": integer,
  "vehicleLabel": string,
  "vehicleStartTime": string,
  "vehicleEndTime": string,
  "endLoads": [
    {
      object (CapacityQuantity)
    }
  ],
  "visits": [
    {
      object (Visit)
    }
  ],
  "transitions": [
    {
      object (Transition)
    }
  ],
  "travelSteps": [
    {
      object (TravelStep)
    }
  ],
  "vehicleDetour": string,
  "hasTrafficInfeasibilities": boolean,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "breaks": [
    {
      object (Break)
    }
  ],
  "delayBeforeVehicleEnd": {
    object (Delay)
  }
}
Fields
vehicleIndex

integer

Vehicle performing the route, identified by its index in the source ShipmentModel.
vehicleLabel

string

Label of the vehicle performing this route, equal to ShipmentModel.vehicles(vehicleIndex).label, if specified.
vehicleStartTime

string (Timestamp format)

Time at which the vehicle starts its route.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
vehicleEndTime

string (Timestamp format)

Time at which the vehicle finishes its route.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
endLoads[]
(deprecated)

object (CapacityQuantity)

DEPRECATED Vehicle loads upon arrival at its end location, for each type specified in Vehicle.capacities, startLoadIntervals, endLoadIntervals or demands. Exception: we omit loads for quantity types unconstrained by intervals and that don't have any non-zero demand on the route.
visits[]

object (Visit)

Ordered sequence of visits representing a route. visits[i] is the i-th visit in the route. If this field is empty, the vehicle is considered as unused.
transitions[]

object (Transition)

Ordered list of transitions for the route.
travelSteps[]
(deprecated)

object (TravelStep)

DEPRECATED Ordered list of travel steps for the route.
vehicleDetour
(deprecated)

string (Duration format)

DEPRECATED This field will only be populated at the ShipmentRoute.Visit level. Extra detour time due to the shipments visited on the route.

It is equal to vehicleEndTime - vehicleStartTime - travel duration from the vehicle's startLocation to its endLocation.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".
hasTrafficInfeasibilities

boolean

When OptimizeToursRequest.consider_road_traffic, is set to true, this field indicates that inconsistencies in route timings are predicted using traffic-based travel duration estimates. There may be insufficient time to complete traffic-adjusted travel, delays, and breaks between visits, before the first visit, or after the last visit, while still satisfying the visit and vehicle time windows. For example,

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

Arrival at next_visit will likely happen later than its current time window due the increased estimate of travel time travelDuration(previous_visit, next_visit) due to traffic. Also, a break may be forced to overlap with a visit due to an increase in travel time estimates and visit or break time window restrictions.
routePolyline

object (EncodedPolyline)

The encoded polyline representation of the route. This field is only populated if OptimizeToursRequest.populate_polylines is set to true.
breaks[]

object (Break)

Breaks scheduled for the vehicle performing this route. The breaks sequence represents time intervals, each starting at the corresponding startTime and lasting duration seconds.
delayBeforeVehicleEnd
(deprecated)

object (Delay)

DEPRECATED Delay occurring before the vehicle end. See TransitionAttributes.delay.

Visit

A visit performed during a route. This visit corresponds to a pickup or a delivery of a Shipment.

JSON representation 
{
  "shipmentIndex": integer,
  "isPickup": boolean,
  "visitRequestIndex": integer,
  "startTime": string,
  "arrivalLoads": [
    {
      object (CapacityQuantity)
    }
  ],
  "detour": string,
  "delayBeforeStart": {
    object (Delay)
  },
  "shipmentLabel": string,
  "visitLabel": string
}
Fields
shipmentIndex

integer

Index of the shipments field in the source ShipmentModel.
isPickup

boolean

If true the visit corresponds to a pickup of a Shipment. Otherwise, it corresponds to a delivery.
visitRequestIndex

integer

Index of VisitRequest in either the pickup or delivery field of the Shipment (see isPickup).
startTime

string (Timestamp format)

Time at which the visit starts. Note that the vehicle may arrive earlier than this at the visit location. Times are consistent with the ShipmentModel.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
arrivalLoads[]
(deprecated)

object (CapacityQuantity)

DEPRECATED Vehicle loads upon arrival at the visit location, for each type specified in Vehicle.capacities, startLoadIntervals, endLoadIntervals or demands.

Exception: we omit loads for quantity types unconstrained by intervals and that don't have any non-zero demand on the route.
detour

string (Duration format)

Extra detour time due to the shipments visited on the route before the visit and to the potential waiting time induced by time windows. If the visit is a delivery, the detour is computed from the corresponding pickup visit and is equal to:

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

Otherwise, it is computed from the vehicle startLocation and is equal to:

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

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".
delayBeforeStart
(deprecated)

object (Delay)

DEPRECATED Delay occurring before the visit starts.
shipmentLabel

string

Copy of the corresponding Shipment.label, if specified in the Shipment.
visitLabel

string

Copy of the corresponding VisitRequest.label, if specified in the VisitRequest.

Delay

DEPRECATED Time interval spent on the route resulting from a TransitionAttributes.delay.

JSON representation 
{
  "startTime": string,
  "duration": string
}
Fields
startTime

string (Timestamp format)

Start of the delay.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
duration

string (Duration format)

Duration of the delay.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

Transition

Transition between two events on the route. See the description of ShipmentRoute.

If the vehicle does not have a startLocation and/or endLocation, the corresponding travel metrics are 0.

JSON representation 
{
  "travelDuration": string,
  "travelDistanceMeters": number,
  "trafficInfoUnavailable": boolean,
  "delayDuration": string,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "loads": [
    {
      object (CapacityQuantity)
    }
  ]
}
Fields
travelDuration

string (Duration format)

Travel duration during this transition.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".
travelDistanceMeters

number

Distance traveled during the transition.
trafficInfoUnavailable

boolean

When traffic is requested via OptimizeToursRequest.consider_road_traffic, and the traffic info couldn't be retrieved for a Transition, this boolean is set to true. This may be temporary (rare hiccup in the realtime traffic servers) or permanent (no data for this location).
delayDuration

string (Duration format)

Sum of the delay durations applied to this transition. If any, the delay starts exactly delayDuration seconds before the next event (visit or vehicle end). See TransitionAttributes.delay.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".
routePolyline

object (EncodedPolyline)

The encoded polyline representation of the route followed during the transition. This field is only populated if populateTransitionPolylines is set to true.
loads[]

object (CapacityQuantity)

Vehicle loads during this transition, for each type specified in Vehicle.capacities, startLoadIntervals, endLoadIntervals, or Shipment.demands.

Exception: we omit loads for quantity types unconstrained by intervals and that don't have any non-zero demand on the route.

The loads during the first transition (i.e., for each capacity type "t", transitions[0].loads[t]) are the starting loads of the vehicle route. The loads of each subsequent transition are determined, for i > 0, by

transitions[i].loads[t] =
transitions[i-1].loads[t] + visits[i-1].demands[t].

EncodedPolyline

The encoded representation of a polyline. More information on polyline encoding can be found here: https://developers.google.com/maps/documentation/utilities/polylinealgorithm https://developers.google.com/maps/documentation/javascript/reference/geometry#encoding.

JSON representation 
{
  "points": string
}
Fields
points

string

String representing encoded points of the polyline.

TravelStep

DEPRECATED Travel between each visit, along the route: from the vehicle's startLocation to the first visit's arrivalLocation, then from the first visit's departureLocation to the second visit's arrivalLocation, and so on until the vehicle's endLocation. This accounts only for the actual travel between visits, not counting the waiting time, the time spent performing a visit, nor the distance covered during a visit.

Invariant: travel_steps_size() == visits_size() + 1.

If the vehicle does not have a start_ and/or endLocation, the corresponding travel metrics are 0 and/or empty.

JSON representation 
{
  "duration": string,
  "distanceMeters": number,
  "trafficInfoUnavailable": boolean,
  "routePolyline": {
    object (EncodedPolyline)
  }
}
Fields
duration

string (Duration format)

Duration of the travel step.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".
distanceMeters

number

Distance traveled during the step.
trafficInfoUnavailable

boolean

When traffic is requested via OptimizeToursRequest.consider_road_traffic, and the traffic info couldn't be retrieved for a TravelStep, this boolean is set to true. This may be temporary (rare hiccup in the realtime traffic servers) or permanent (no data for this location).
routePolyline

object (EncodedPolyline)

The encoded polyline representation of the route followed during the step.

This field is only populated if OptimizeToursRequest.populate_travel_step_polylines is set to true.

Break

Data representing the execution of a break.

JSON representation 
{
  "startTime": string,
  "duration": string
}
Fields
startTime

string (Timestamp format)

Start time of a break.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
duration

string (Duration format)

Duration of a break.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".