tessl/pypi-google-maps-routeoptimization

Google Maps Route Optimization API client library for assigning tasks and routes to vehicle fleets while optimizing against custom objectives and constraints.

—

Pending

Overview

Eval results

Files

Data Model

Name: tessl/pypi-google-maps-routeoptimization
Author: tessl

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.

Capabilities

Core Model Types

ShipmentModel

The complete model for a route optimization problem containing shipments, vehicles, and global constraints.

class ShipmentModel:
    shipments: Sequence[Shipment]  # Tasks to be performed
    vehicles: Sequence[Vehicle]  # Available fleet
    max_active_vehicles: Optional[int]  # Maximum vehicles to use
    global_start_time: Optional[timestamp_pb2.Timestamp]  # Earliest start time
    global_end_time: Optional[timestamp_pb2.Timestamp]  # Latest end time
    global_duration_cost_per_hour: Optional[float]  # Cost per hour for all vehicles
    duration_distance_matrix: Optional[DistanceMatrix]  # Pre-computed distances
    duration_distance_matrix_src_tags: Sequence[str]  # Source tags for matrix
    duration_distance_matrix_dst_tags: Sequence[str]  # Destination tags for matrix
    transition_attributes: Sequence[TransitionAttributes]  # Custom transition properties
    shipment_type_incompatibilities: Sequence[ShipmentTypeIncompatibility]  # Type conflicts
    shipment_type_requirements: Sequence[ShipmentTypeRequirement]  # Type dependencies
    precedence_rules: Sequence[PrecedenceRule]  # Shipment ordering constraints
    break_rules: Sequence[BreakRule]  # Global break requirements

Shipment

Represents a task requiring pickup and/or delivery operations.

class Shipment:
    display_name: Optional[str]  # Human-readable name
    pickups: Sequence[VisitRequest]  # Pickup requirements
    deliveries: Sequence[VisitRequest]  # Delivery requirements
    load_demands: Mapping[str, LoadDemand]  # Resource requirements (weight, volume, etc.)
    allowed_vehicle_indices: Sequence[int]  # Allowed vehicles by index
    costs_per_vehicle: Sequence[float]  # Per-vehicle costs
    costs_per_vehicle_indices: Sequence[int]  # Vehicle indices for costs
    pickup_to_delivery_absolute_detour_limit: Optional[duration_pb2.Duration]  # Max detour
    pickup_to_delivery_time_limit: Optional[duration_pb2.Duration]  # Max time between pickup/delivery
    shipment_type: Optional[str]  # Type for compatibility rules
    label: Optional[str]  # Unique identifier
    
    class VisitRequest:
        arrival_location: Optional[Location]  # Where to arrive
        arrival_waypoint: Optional[Waypoint]  # Arrival waypoint
        departure_location: Optional[Location]  # Where to depart from
        departure_waypoint: Optional[Waypoint]  # Departure waypoint
        tags: Sequence[str]  # Tags for transition attributes
        time_windows: Sequence[TimeWindow]  # When visit can occur
        duration: Optional[duration_pb2.Duration]  # Service time
        cost: Optional[float]  # Fixed cost for this visit
        load_demands: Mapping[str, LoadDemand]  # Load changes at this visit
        visit_types: Sequence[str]  # Visit type classifications
        label: Optional[str]  # Visit identifier

Vehicle

Represents a vehicle in the fleet with capabilities and constraints.

class Vehicle:
    display_name: Optional[str]  # Human-readable name
    travel_mode: Optional[TravelMode]  # Transportation mode
    start_location: Optional[Location]  # Starting location
    start_waypoint: Optional[Waypoint]  # Starting waypoint
    end_location: Optional[Location]  # Ending location
    end_waypoint: Optional[Waypoint]  # Ending waypoint
    start_tags: Sequence[str]  # Tags for start location
    end_tags: Sequence[str]  # Tags for end location
    start_time_windows: Sequence[TimeWindow]  # When vehicle can start
    end_time_windows: Sequence[TimeWindow]  # When vehicle must return
    travel_duration_multiple: Optional[float]  # Travel time multiplier
    unloading_policy: Optional[UnloadingPolicy]  # Unloading behavior
    load_limits: Mapping[str, LoadLimit]  # Capacity constraints
    cost_per_hour: Optional[float]  # Hourly cost
    cost_per_traveled_hour: Optional[float]  # Cost per hour while traveling
    cost_per_kilometer: Optional[float]  # Distance-based cost
    fixed_cost: Optional[float]  # Fixed cost for using vehicle
    used_if_route_is_empty: Optional[bool]  # Include empty routes in cost
    route_duration_limit: Optional[DurationLimit]  # Max route duration
    travel_duration_limit: Optional[DurationLimit]  # Max travel time
    route_distance_limit: Optional[DistanceLimit]  # Max route distance
    extra_visit_duration_for_visit_type: Mapping[str, duration_pb2.Duration]  # Extra time by visit type
    break_rule: Optional[BreakRule]  # Driver break requirements
    label: Optional[str]  # Vehicle identifier
    ignore: Optional[bool]  # Exclude from optimization

Location and Navigation Types

Location

Geographic location specification.

class Location:
    lat_lng: Optional[latlng_pb2.LatLng]  # GPS coordinates
    heading: Optional[int]  # Direction in degrees (0-360)

Waypoint

Point along a route with location and navigation options.

class Waypoint:
    location: Optional[Location]  # Geographic location
    place_id: Optional[str]  # Google Places ID
    via: Optional[bool]  # Pass-through point (don't stop)

Time and Constraint Types

TimeWindow

Time interval constraint for visits or vehicle availability.

class TimeWindow:
    start_time: Optional[timestamp_pb2.Timestamp]  # Window start
    end_time: Optional[timestamp_pb2.Timestamp]  # Window end
    soft_start_time: Optional[timestamp_pb2.Timestamp]  # Preferred start (with penalty)
    soft_end_time: Optional[timestamp_pb2.Timestamp]  # Preferred end (with penalty)
    cost_per_hour_after_soft_end_time: Optional[float]  # Late penalty

BreakRule

Driver break requirements and constraints.

class BreakRule:
    break_requests: Sequence[BreakRequest]  # Specific break requirements
    frequency_constraints: Sequence[FrequencyConstraint]  # Break frequency rules
    
    class BreakRequest:
        earliest_start_time: Optional[timestamp_pb2.Timestamp]  # Earliest break start
        latest_start_time: Optional[timestamp_pb2.Timestamp]  # Latest break start
        min_duration: Optional[duration_pb2.Duration]  # Minimum break duration
    
    class FrequencyConstraint:
        min_break_duration: Optional[duration_pb2.Duration]  # Minimum individual break
        max_inter_break_duration: Optional[duration_pb2.Duration]  # Max time between breaks

DistanceLimit

Vehicle distance constraints with penalties.

class DistanceLimit:
    max_meters: Optional[int]  # Hard distance limit
    soft_max_meters: Optional[int]  # Soft distance limit (with penalty)
    cost_per_kilometer_above_soft_max: Optional[float]  # Overage penalty

Load and Capacity Types

LoadDemand

Resource demand specification for shipments.

class LoadDemand:
    amount: Optional[int]  # Demand amount (positive for pickup, negative for delivery)

LoadLimit

Vehicle capacity specification.

class LoadLimit:
    max_load: Optional[int]  # Maximum capacity
    soft_max_load: Optional[int]  # Soft capacity limit (with penalty)
    cost_per_unit_above_soft_max: Optional[float]  # Overload penalty
    start_load_interval: Optional[Interval]  # Starting load range
    end_load_interval: Optional[Interval]  # Ending load range

Routing and Navigation Types

RouteModifiers

Route calculation preferences and restrictions.

class RouteModifiers:
    avoid_tolls: Optional[bool]  # Avoid toll roads
    avoid_highways: Optional[bool]  # Avoid highways
    avoid_ferries: Optional[bool]  # Avoid ferries
    avoid_indoor: Optional[bool]  # Avoid indoor routing

TransitionAttributes

Custom attributes for transitions between locations.

class TransitionAttributes:
    src_tag: Optional[str]  # Source location tag
    dst_tag: Optional[str]  # Destination location tag
    distance_meters: Optional[float]  # Override distance
    delay: Optional[duration_pb2.Duration]  # Additional delay
    cost: Optional[float]  # Fixed transition cost
    cost_per_kilometer: Optional[float]  # Distance-based cost

Constraint Types

ShipmentTypeIncompatibility

Defines shipment types that cannot be on the same vehicle.

class ShipmentTypeIncompatibility:
    types: Sequence[str]  # Incompatible shipment types
    incompatibility_mode: Optional[IncompatibilityMode]  # How to apply incompatibility
    
    class IncompatibilityMode(enum.Enum):
        SAME_VEHICLE_AT_PICKUP_TIME = 0  # Same vehicle at pickup
        SAME_VEHICLE_AT_DELIVERY_TIME = 1  # Same vehicle at delivery

ShipmentTypeRequirement

Shipment type dependency requirements.

class ShipmentTypeRequirement:
    required_shipment_type_alternatives: Sequence[str]  # Required types (any of)
    dependent_shipment_types: Sequence[str]  # Types that depend on required types
    requirement_mode: Optional[RequirementMode]  # How to apply requirement
    
    class RequirementMode(enum.Enum):
        PERFORMED_BY_SAME_VEHICLE = 0  # Same vehicle must handle both
        IN_SAME_VEHICLE_AT_PICKUP_TIME = 1  # Same vehicle at pickup
        IN_SAME_VEHICLE_AT_DELIVERY_TIME = 2  # Same vehicle at delivery

Enums

TravelMode

class TravelMode(enum.Enum):
    TRAVEL_MODE_UNSPECIFIED = 0
    DRIVING = 1  # Car/truck driving
    WALKING = 2  # Walking

UnloadingPolicy

class UnloadingPolicy(enum.Enum):
    UNLOADING_POLICY_UNSPECIFIED = 0
    LAST_IN_FIRST_OUT = 1  # LIFO unloading
    FIRST_IN_FIRST_OUT = 2  # FIFO unloading

Usage Examples

Creating a Basic Shipment Model

from google.maps import routeoptimization_v1
from google.protobuf import timestamp_pb2, duration_pb2

# Create a shipment model with one delivery task and one vehicle
model = routeoptimization_v1.ShipmentModel(
    # Global time window: 8 AM to 6 PM
    global_start_time=timestamp_pb2.Timestamp(seconds=1640775600),  # 8 AM
    global_end_time=timestamp_pb2.Timestamp(seconds=1640811600),    # 6 PM
    
    shipments=[
        routeoptimization_v1.Shipment(
            display_name="Package Delivery",
            deliveries=[
                routeoptimization_v1.Shipment.VisitRequest(
                    arrival_location=routeoptimization_v1.Location(
                        lat_lng={"latitude": 37.7749, "longitude": -122.4194}
                    ),
                    time_windows=[
                        routeoptimization_v1.TimeWindow(
                            start_time=timestamp_pb2.Timestamp(seconds=1640782800),  # 10 AM
                            end_time=timestamp_pb2.Timestamp(seconds=1640793600)     # 1 PM
                        )
                    ],
                    duration=duration_pb2.Duration(seconds=300),  # 5 minutes
                    load_demands={
                        "weight": routeoptimization_v1.LoadDemand(amount=-10)  # Delivery: negative amount
                    }
                )
            ]
        )
    ],
    
    vehicles=[
        routeoptimization_v1.Vehicle(
            display_name="Delivery Truck",
            start_location=routeoptimization_v1.Location(
                lat_lng={"latitude": 37.7649, "longitude": -122.4294}
            ),
            end_location=routeoptimization_v1.Location(
                lat_lng={"latitude": 37.7649, "longitude": -122.4294}
            ),
            load_limits={
                "weight": routeoptimization_v1.LoadLimit(max_load=100)  # 100 units capacity
            },
            cost_per_hour=25.0,
            cost_per_kilometer=1.5
        )
    ]
)

Advanced Constraints Example

from google.maps import routeoptimization_v1

# Create model with advanced constraints
model = routeoptimization_v1.ShipmentModel(
    shipments=[
        routeoptimization_v1.Shipment(
            display_name="Fragile Items",
            shipment_type="fragile",
            pickups=[
                routeoptimization_v1.Shipment.VisitRequest(
                    arrival_location=routeoptimization_v1.Location(
                        lat_lng={"latitude": 37.7649, "longitude": -122.4294}
                    ),
                    tags=["warehouse"],  # Tag for transition attributes
                    duration=duration_pb2.Duration(seconds=600)  # 10 minutes loading
                )
            ],
            deliveries=[
                routeoptimization_v1.Shipment.VisitRequest(
                    arrival_location=routeoptimization_v1.Location(
                        lat_lng={"latitude": 37.7749, "longitude": -122.4194}
                    ),
                    tags=["customer"],
                    duration=duration_pb2.Duration(seconds=300)
                )
            ],
            pickup_to_delivery_time_limit=duration_pb2.Duration(seconds=7200)  # Max 2 hours
        )
    ],
    
    vehicles=[
        routeoptimization_v1.Vehicle(
            display_name="Specialized Vehicle",
            break_rule=routeoptimization_v1.BreakRule(
                break_requests=[
                    routeoptimization_v1.BreakRule.BreakRequest(
                        earliest_start_time=timestamp_pb2.Timestamp(seconds=1640793600),  # 1 PM
                        latest_start_time=timestamp_pb2.Timestamp(seconds=1640797200),   # 2 PM
                        min_duration=duration_pb2.Duration(seconds=1800)  # 30 minutes
                    )
                ]
            ),
            route_distance_limit=routeoptimization_v1.DistanceLimit(
                max_meters=100000,  # 100 km hard limit
                soft_max_meters=80000,  # 80 km soft limit
                cost_per_kilometer_above_soft_max=2.0  # Penalty for exceeding
            )
        )
    ],
    
    # Incompatible shipment types
    shipment_type_incompatibilities=[
        routeoptimization_v1.ShipmentTypeIncompatibility(
            types=["fragile", "hazardous"],
            incompatibility_mode=routeoptimization_v1.ShipmentTypeIncompatibility.IncompatibilityMode.SAME_VEHICLE_AT_PICKUP_TIME
        )
    ],
    
    # Custom transition attributes
    transition_attributes=[
        routeoptimization_v1.TransitionAttributes(
            src_tag="warehouse",
            dst_tag="customer",
            delay=duration_pb2.Duration(seconds=300),  # 5 minute setup delay
            cost=5.0  # Additional cost
        )
    ]
)

Install with Tessl CLI

npx tessl i tessl/pypi-google-maps-routeoptimization

docs

batch-operations.md

client-configuration.md

data-model.md

index.md

route-optimization.md

tile.json