Google Maps Route Optimization V1 Client - Class ShipmentRoute (0.3.1)

Reference documentation and code samples for the Google Maps Route Optimization V1 Client class 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: php ---+-------------------------------------+-----------------------------+--> | 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: php 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 | | | | || || | | | | | | || --++-----------------------------------------------------------------++-->

Generated from protobuf message google.maps.routeoptimization.v1.ShipmentRoute

Namespace

Google \ Maps \ RouteOptimization \ V1

Methods

__construct

Constructor.

Parameters
Name Description
data array

Optional. Data for populating the Message object.
↳ vehicle_index int

Vehicle performing the route, identified by its index in the source ShipmentModel.
↳ vehicle_label string

Label of the vehicle performing this route, equal to ShipmentModel.vehicles(vehicle_index).label, if specified.
↳ vehicle_start_time Google\Protobuf\Timestamp

Time at which the vehicle starts its route.
↳ vehicle_end_time Google\Protobuf\Timestamp

Time at which the vehicle finishes its route.
↳ visits array<ShipmentRoute\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 array<ShipmentRoute\Transition>

Ordered list of transitions for the route.
↳ has_traffic_infeasibilities bool

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, start_time(previous_visit) + duration(previous_visit) + travel_duration(previous_visit, next_visit) > start_time(next_visit) Arrival at next_visit will likely happen later than its current time window due the increased estimate of travel time travel_duration(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.
↳ route_polyline ShipmentRoute\EncodedPolyline

The encoded polyline representation of the route. This field is only populated if OptimizeToursRequest.populate_polylines is set to true.
↳ breaks array<ShipmentRoute\PBBreak>

Breaks scheduled for the vehicle performing this route. The breaks sequence represents time intervals, each starting at the corresponding start_time and lasting duration seconds.
↳ metrics AggregatedMetrics

Duration, distance and load metrics for this route. The fields of AggregatedMetrics are summed over all ShipmentRoute.transitions or ShipmentRoute.visits, depending on the context.
↳ route_costs array|Google\Protobuf\Internal\MapField

Cost of the route, broken down by cost-related request fields. The keys are proto paths, relative to the input OptimizeToursRequest, e.g. "model.shipments.pickups.cost", and the values are the total cost generated by the corresponding cost field, aggregated over the whole route. In other words, costs["model.shipments.pickups.cost"] is the sum of all pickup costs over the route. All costs defined in the model are reported in detail here with the exception of costs related to TransitionAttributes that are only reported in an aggregated way as of 2022/01.
↳ route_total_cost float

Total cost of the route. The sum of all costs in the cost map.

getVehicleIndex

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

Returns
Type Description
int

setVehicleIndex

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

Parameter
Name Description
var int
Returns
Type Description
$this

getVehicleLabel

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

Returns
Type Description
string

setVehicleLabel

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

Parameter
Name Description
var string
Returns
Type Description
$this

getVehicleStartTime

Time at which the vehicle starts its route.

Returns
Type Description
Google\Protobuf\Timestamp|null

hasVehicleStartTime

clearVehicleStartTime

setVehicleStartTime

Time at which the vehicle starts its route.

Parameter
Name Description
var Google\Protobuf\Timestamp
Returns
Type Description
$this

getVehicleEndTime

Time at which the vehicle finishes its route.

Returns
Type Description
Google\Protobuf\Timestamp|null

hasVehicleEndTime

clearVehicleEndTime

setVehicleEndTime

Time at which the vehicle finishes its route.

Parameter
Name Description
var Google\Protobuf\Timestamp
Returns
Type Description
$this

getVisits

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.

Returns
Type Description
Google\Protobuf\Internal\RepeatedField

setVisits

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.

Parameter
Name Description
var array<ShipmentRoute\Visit>
Returns
Type Description
$this

getTransitions

Ordered list of transitions for the route.

Returns
Type Description
Google\Protobuf\Internal\RepeatedField

setTransitions

Ordered list of transitions for the route.

Parameter
Name Description
var array<ShipmentRoute\Transition>
Returns
Type Description
$this

getHasTrafficInfeasibilities

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,

  start_time(previous_visit) + duration(previous_visit) +
  travel_duration(previous_visit, next_visit) > start_time(next_visit)

Arrival at next_visit will likely happen later than its current time window due the increased estimate of travel time travel_duration(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.

Returns
Type Description
bool

setHasTrafficInfeasibilities

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,

  start_time(previous_visit) + duration(previous_visit) +
  travel_duration(previous_visit, next_visit) > start_time(next_visit)

Arrival at next_visit will likely happen later than its current time window due the increased estimate of travel time travel_duration(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.

Parameter
Name Description
var bool
Returns
Type Description
$this

getRoutePolyline

The encoded polyline representation of the route.

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

Returns
Type Description
ShipmentRoute\EncodedPolyline|null

hasRoutePolyline

clearRoutePolyline

setRoutePolyline

The encoded polyline representation of the route.

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

Parameter
Name Description
var ShipmentRoute\EncodedPolyline
Returns
Type Description
$this

getBreaks

Breaks scheduled for the vehicle performing this route.

The breaks sequence represents time intervals, each starting at the corresponding start_time and lasting duration seconds.

Returns
Type Description
Google\Protobuf\Internal\RepeatedField

setBreaks

Breaks scheduled for the vehicle performing this route.

The breaks sequence represents time intervals, each starting at the corresponding start_time and lasting duration seconds.

Parameter
Name Description
var array<ShipmentRoute\PBBreak>
Returns
Type Description
$this

getMetrics

Duration, distance and load metrics for this route. The fields of AggregatedMetrics are summed over all ShipmentRoute.transitions or ShipmentRoute.visits, depending on the context.

Returns
Type Description
AggregatedMetrics|null

hasMetrics

clearMetrics

setMetrics

Duration, distance and load metrics for this route. The fields of AggregatedMetrics are summed over all ShipmentRoute.transitions or ShipmentRoute.visits, depending on the context.

Parameter
Name Description
var AggregatedMetrics
Returns
Type Description
$this

getRouteCosts

Cost of the route, broken down by cost-related request fields.

The keys are proto paths, relative to the input OptimizeToursRequest, e.g. "model.shipments.pickups.cost", and the values are the total cost generated by the corresponding cost field, aggregated over the whole route. In other words, costs["model.shipments.pickups.cost"] is the sum of all pickup costs over the route. All costs defined in the model are reported in detail here with the exception of costs related to TransitionAttributes that are only reported in an aggregated way as of 2022/01.

Returns
Type Description
Google\Protobuf\Internal\MapField

setRouteCosts

Cost of the route, broken down by cost-related request fields.

The keys are proto paths, relative to the input OptimizeToursRequest, e.g. "model.shipments.pickups.cost", and the values are the total cost generated by the corresponding cost field, aggregated over the whole route. In other words, costs["model.shipments.pickups.cost"] is the sum of all pickup costs over the route. All costs defined in the model are reported in detail here with the exception of costs related to TransitionAttributes that are only reported in an aggregated way as of 2022/01.

Parameter
Name Description
var array|Google\Protobuf\Internal\MapField
Returns
Type Description
$this

getRouteTotalCost

Total cost of the route. The sum of all costs in the cost map.

Returns
Type Description
float

setRouteTotalCost

Total cost of the route. The sum of all costs in the cost map.

Parameter
Name Description
var float
Returns
Type Description
$this