0
# Data Model
1
2
Comprehensive data model for representing route optimization problems including shipments, vehicles, constraints, time windows, and optimization parameters. These classes form the foundation for describing complex vehicle routing problems with rich constraint support.
3
4
## Capabilities
5
6
### Core Model Types
7
8
#### ShipmentModel
9
10
The complete model for a route optimization problem containing shipments, vehicles, and global constraints.
11
12
```python { .api }
13
class ShipmentModel:
14
shipments: Sequence[Shipment] # Tasks to be performed
15
vehicles: Sequence[Vehicle] # Available fleet
16
max_active_vehicles: Optional[int] # Maximum vehicles to use
17
global_start_time: Optional[timestamp_pb2.Timestamp] # Earliest start time
18
global_end_time: Optional[timestamp_pb2.Timestamp] # Latest end time
19
global_duration_cost_per_hour: Optional[float] # Cost per hour for all vehicles
20
duration_distance_matrix: Optional[DistanceMatrix] # Pre-computed distances
21
duration_distance_matrix_src_tags: Sequence[str] # Source tags for matrix
22
duration_distance_matrix_dst_tags: Sequence[str] # Destination tags for matrix
23
transition_attributes: Sequence[TransitionAttributes] # Custom transition properties
24
shipment_type_incompatibilities: Sequence[ShipmentTypeIncompatibility] # Type conflicts
25
shipment_type_requirements: Sequence[ShipmentTypeRequirement] # Type dependencies
26
precedence_rules: Sequence[PrecedenceRule] # Shipment ordering constraints
27
break_rules: Sequence[BreakRule] # Global break requirements
28
```
29
30
#### Shipment
31
32
Represents a task requiring pickup and/or delivery operations.
33
34
```python { .api }
35
class Shipment:
36
display_name: Optional[str] # Human-readable name
37
pickups: Sequence[VisitRequest] # Pickup requirements
38
deliveries: Sequence[VisitRequest] # Delivery requirements
39
load_demands: Mapping[str, LoadDemand] # Resource requirements (weight, volume, etc.)
40
allowed_vehicle_indices: Sequence[int] # Allowed vehicles by index
41
costs_per_vehicle: Sequence[float] # Per-vehicle costs
42
costs_per_vehicle_indices: Sequence[int] # Vehicle indices for costs
43
pickup_to_delivery_absolute_detour_limit: Optional[duration_pb2.Duration] # Max detour
44
pickup_to_delivery_time_limit: Optional[duration_pb2.Duration] # Max time between pickup/delivery
45
shipment_type: Optional[str] # Type for compatibility rules
46
label: Optional[str] # Unique identifier
47
48
class VisitRequest:
49
arrival_location: Optional[Location] # Where to arrive
50
arrival_waypoint: Optional[Waypoint] # Arrival waypoint
51
departure_location: Optional[Location] # Where to depart from
52
departure_waypoint: Optional[Waypoint] # Departure waypoint
53
tags: Sequence[str] # Tags for transition attributes
54
time_windows: Sequence[TimeWindow] # When visit can occur
55
duration: Optional[duration_pb2.Duration] # Service time
56
cost: Optional[float] # Fixed cost for this visit
57
load_demands: Mapping[str, LoadDemand] # Load changes at this visit
58
visit_types: Sequence[str] # Visit type classifications
59
label: Optional[str] # Visit identifier
60
```
61
62
#### Vehicle
63
64
Represents a vehicle in the fleet with capabilities and constraints.
65
66
```python { .api }
67
class Vehicle:
68
display_name: Optional[str] # Human-readable name
69
travel_mode: Optional[TravelMode] # Transportation mode
70
start_location: Optional[Location] # Starting location
71
start_waypoint: Optional[Waypoint] # Starting waypoint
72
end_location: Optional[Location] # Ending location
73
end_waypoint: Optional[Waypoint] # Ending waypoint
74
start_tags: Sequence[str] # Tags for start location
75
end_tags: Sequence[str] # Tags for end location
76
start_time_windows: Sequence[TimeWindow] # When vehicle can start
77
end_time_windows: Sequence[TimeWindow] # When vehicle must return
78
travel_duration_multiple: Optional[float] # Travel time multiplier
79
unloading_policy: Optional[UnloadingPolicy] # Unloading behavior
80
load_limits: Mapping[str, LoadLimit] # Capacity constraints
81
cost_per_hour: Optional[float] # Hourly cost
82
cost_per_traveled_hour: Optional[float] # Cost per hour while traveling
83
cost_per_kilometer: Optional[float] # Distance-based cost
84
fixed_cost: Optional[float] # Fixed cost for using vehicle
85
used_if_route_is_empty: Optional[bool] # Include empty routes in cost
86
route_duration_limit: Optional[DurationLimit] # Max route duration
87
travel_duration_limit: Optional[DurationLimit] # Max travel time
88
route_distance_limit: Optional[DistanceLimit] # Max route distance
89
extra_visit_duration_for_visit_type: Mapping[str, duration_pb2.Duration] # Extra time by visit type
90
break_rule: Optional[BreakRule] # Driver break requirements
91
label: Optional[str] # Vehicle identifier
92
ignore: Optional[bool] # Exclude from optimization
93
```
94
95
### Location and Navigation Types
96
97
#### Location
98
99
Geographic location specification.
100
101
```python { .api }
102
class Location:
103
lat_lng: Optional[latlng_pb2.LatLng] # GPS coordinates
104
heading: Optional[int] # Direction in degrees (0-360)
105
```
106
107
#### Waypoint
108
109
Point along a route with location and navigation options.
110
111
```python { .api }
112
class Waypoint:
113
location: Optional[Location] # Geographic location
114
place_id: Optional[str] # Google Places ID
115
via: Optional[bool] # Pass-through point (don't stop)
116
```
117
118
### Time and Constraint Types
119
120
#### TimeWindow
121
122
Time interval constraint for visits or vehicle availability.
123
124
```python { .api }
125
class TimeWindow:
126
start_time: Optional[timestamp_pb2.Timestamp] # Window start
127
end_time: Optional[timestamp_pb2.Timestamp] # Window end
128
soft_start_time: Optional[timestamp_pb2.Timestamp] # Preferred start (with penalty)
129
soft_end_time: Optional[timestamp_pb2.Timestamp] # Preferred end (with penalty)
130
cost_per_hour_after_soft_end_time: Optional[float] # Late penalty
131
```
132
133
#### BreakRule
134
135
Driver break requirements and constraints.
136
137
```python { .api }
138
class BreakRule:
139
break_requests: Sequence[BreakRequest] # Specific break requirements
140
frequency_constraints: Sequence[FrequencyConstraint] # Break frequency rules
141
142
class BreakRequest:
143
earliest_start_time: Optional[timestamp_pb2.Timestamp] # Earliest break start
144
latest_start_time: Optional[timestamp_pb2.Timestamp] # Latest break start
145
min_duration: Optional[duration_pb2.Duration] # Minimum break duration
146
147
class FrequencyConstraint:
148
min_break_duration: Optional[duration_pb2.Duration] # Minimum individual break
149
max_inter_break_duration: Optional[duration_pb2.Duration] # Max time between breaks
150
```
151
152
#### DistanceLimit
153
154
Vehicle distance constraints with penalties.
155
156
```python { .api }
157
class DistanceLimit:
158
max_meters: Optional[int] # Hard distance limit
159
soft_max_meters: Optional[int] # Soft distance limit (with penalty)
160
cost_per_kilometer_above_soft_max: Optional[float] # Overage penalty
161
```
162
163
### Load and Capacity Types
164
165
#### LoadDemand
166
167
Resource demand specification for shipments.
168
169
```python { .api }
170
class LoadDemand:
171
amount: Optional[int] # Demand amount (positive for pickup, negative for delivery)
172
```
173
174
#### LoadLimit
175
176
Vehicle capacity specification.
177
178
```python { .api }
179
class LoadLimit:
180
max_load: Optional[int] # Maximum capacity
181
soft_max_load: Optional[int] # Soft capacity limit (with penalty)
182
cost_per_unit_above_soft_max: Optional[float] # Overload penalty
183
start_load_interval: Optional[Interval] # Starting load range
184
end_load_interval: Optional[Interval] # Ending load range
185
```
186
187
### Routing and Navigation Types
188
189
#### RouteModifiers
190
191
Route calculation preferences and restrictions.
192
193
```python { .api }
194
class RouteModifiers:
195
avoid_tolls: Optional[bool] # Avoid toll roads
196
avoid_highways: Optional[bool] # Avoid highways
197
avoid_ferries: Optional[bool] # Avoid ferries
198
avoid_indoor: Optional[bool] # Avoid indoor routing
199
```
200
201
#### TransitionAttributes
202
203
Custom attributes for transitions between locations.
204
205
```python { .api }
206
class TransitionAttributes:
207
src_tag: Optional[str] # Source location tag
208
dst_tag: Optional[str] # Destination location tag
209
distance_meters: Optional[float] # Override distance
210
delay: Optional[duration_pb2.Duration] # Additional delay
211
cost: Optional[float] # Fixed transition cost
212
cost_per_kilometer: Optional[float] # Distance-based cost
213
```
214
215
### Constraint Types
216
217
#### ShipmentTypeIncompatibility
218
219
Defines shipment types that cannot be on the same vehicle.
220
221
```python { .api }
222
class ShipmentTypeIncompatibility:
223
types: Sequence[str] # Incompatible shipment types
224
incompatibility_mode: Optional[IncompatibilityMode] # How to apply incompatibility
225
226
class IncompatibilityMode(enum.Enum):
227
SAME_VEHICLE_AT_PICKUP_TIME = 0 # Same vehicle at pickup
228
SAME_VEHICLE_AT_DELIVERY_TIME = 1 # Same vehicle at delivery
229
```
230
231
#### ShipmentTypeRequirement
232
233
Shipment type dependency requirements.
234
235
```python { .api }
236
class ShipmentTypeRequirement:
237
required_shipment_type_alternatives: Sequence[str] # Required types (any of)
238
dependent_shipment_types: Sequence[str] # Types that depend on required types
239
requirement_mode: Optional[RequirementMode] # How to apply requirement
240
241
class RequirementMode(enum.Enum):
242
PERFORMED_BY_SAME_VEHICLE = 0 # Same vehicle must handle both
243
IN_SAME_VEHICLE_AT_PICKUP_TIME = 1 # Same vehicle at pickup
244
IN_SAME_VEHICLE_AT_DELIVERY_TIME = 2 # Same vehicle at delivery
245
```
246
247
### Enums
248
249
#### TravelMode
250
251
```python { .api }
252
class TravelMode(enum.Enum):
253
TRAVEL_MODE_UNSPECIFIED = 0
254
DRIVING = 1 # Car/truck driving
255
WALKING = 2 # Walking
256
```
257
258
#### UnloadingPolicy
259
260
```python { .api }
261
class UnloadingPolicy(enum.Enum):
262
UNLOADING_POLICY_UNSPECIFIED = 0
263
LAST_IN_FIRST_OUT = 1 # LIFO unloading
264
FIRST_IN_FIRST_OUT = 2 # FIFO unloading
265
```
266
267
## Usage Examples
268
269
### Creating a Basic Shipment Model
270
271
```python
272
from google.maps import routeoptimization_v1
273
from google.protobuf import timestamp_pb2, duration_pb2
274
275
# Create a shipment model with one delivery task and one vehicle
276
model = routeoptimization_v1.ShipmentModel(
277
# Global time window: 8 AM to 6 PM
278
global_start_time=timestamp_pb2.Timestamp(seconds=1640775600), # 8 AM
279
global_end_time=timestamp_pb2.Timestamp(seconds=1640811600), # 6 PM
280
281
shipments=[
282
routeoptimization_v1.Shipment(
283
display_name="Package Delivery",
284
deliveries=[
285
routeoptimization_v1.Shipment.VisitRequest(
286
arrival_location=routeoptimization_v1.Location(
287
lat_lng={"latitude": 37.7749, "longitude": -122.4194}
288
),
289
time_windows=[
290
routeoptimization_v1.TimeWindow(
291
start_time=timestamp_pb2.Timestamp(seconds=1640782800), # 10 AM
292
end_time=timestamp_pb2.Timestamp(seconds=1640793600) # 1 PM
293
)
294
],
295
duration=duration_pb2.Duration(seconds=300), # 5 minutes
296
load_demands={
297
"weight": routeoptimization_v1.LoadDemand(amount=-10) # Delivery: negative amount
298
}
299
)
300
]
301
)
302
],
303
304
vehicles=[
305
routeoptimization_v1.Vehicle(
306
display_name="Delivery Truck",
307
start_location=routeoptimization_v1.Location(
308
lat_lng={"latitude": 37.7649, "longitude": -122.4294}
309
),
310
end_location=routeoptimization_v1.Location(
311
lat_lng={"latitude": 37.7649, "longitude": -122.4294}
312
),
313
load_limits={
314
"weight": routeoptimization_v1.LoadLimit(max_load=100) # 100 units capacity
315
},
316
cost_per_hour=25.0,
317
cost_per_kilometer=1.5
318
)
319
]
320
)
321
```
322
323
### Advanced Constraints Example
324
325
```python
326
from google.maps import routeoptimization_v1
327
328
# Create model with advanced constraints
329
model = routeoptimization_v1.ShipmentModel(
330
shipments=[
331
routeoptimization_v1.Shipment(
332
display_name="Fragile Items",
333
shipment_type="fragile",
334
pickups=[
335
routeoptimization_v1.Shipment.VisitRequest(
336
arrival_location=routeoptimization_v1.Location(
337
lat_lng={"latitude": 37.7649, "longitude": -122.4294}
338
),
339
tags=["warehouse"], # Tag for transition attributes
340
duration=duration_pb2.Duration(seconds=600) # 10 minutes loading
341
)
342
],
343
deliveries=[
344
routeoptimization_v1.Shipment.VisitRequest(
345
arrival_location=routeoptimization_v1.Location(
346
lat_lng={"latitude": 37.7749, "longitude": -122.4194}
347
),
348
tags=["customer"],
349
duration=duration_pb2.Duration(seconds=300)
350
)
351
],
352
pickup_to_delivery_time_limit=duration_pb2.Duration(seconds=7200) # Max 2 hours
353
)
354
],
355
356
vehicles=[
357
routeoptimization_v1.Vehicle(
358
display_name="Specialized Vehicle",
359
break_rule=routeoptimization_v1.BreakRule(
360
break_requests=[
361
routeoptimization_v1.BreakRule.BreakRequest(
362
earliest_start_time=timestamp_pb2.Timestamp(seconds=1640793600), # 1 PM
363
latest_start_time=timestamp_pb2.Timestamp(seconds=1640797200), # 2 PM
364
min_duration=duration_pb2.Duration(seconds=1800) # 30 minutes
365
)
366
]
367
),
368
route_distance_limit=routeoptimization_v1.DistanceLimit(
369
max_meters=100000, # 100 km hard limit
370
soft_max_meters=80000, # 80 km soft limit
371
cost_per_kilometer_above_soft_max=2.0 # Penalty for exceeding
372
)
373
)
374
],
375
376
# Incompatible shipment types
377
shipment_type_incompatibilities=[
378
routeoptimization_v1.ShipmentTypeIncompatibility(
379
types=["fragile", "hazardous"],
380
incompatibility_mode=routeoptimization_v1.ShipmentTypeIncompatibility.IncompatibilityMode.SAME_VEHICLE_AT_PICKUP_TIME
381
)
382
],
383
384
# Custom transition attributes
385
transition_attributes=[
386
routeoptimization_v1.TransitionAttributes(
387
src_tag="warehouse",
388
dst_tag="customer",
389
delay=duration_pb2.Duration(seconds=300), # 5 minute setup delay
390
cost=5.0 # Additional cost
391
)
392
]
393
)
394
```