Skill: shaharsha/google-maps (version 3.2.0)

--- name: google-maps description: > Google Maps integration for OpenClaw with Routes API. Use for: (1) Distance/travel time calculations with traffic prediction, (2) Turn-by-turn directions, (3) Distance matrix between multiple points, (4) Geocoding addresses to coordinates and reverse, (5) Places search and details, (6) Transit planning with arrival times. Supports future departure times, traffic models (pessimistic/optimistic), avoid options (tolls/highways), and multiple travel modes (driving/walking/bicycling/transit). version: 3.2.0 author: Leo 🦁 tags: [maps, places, location, navigation, google, traffic, directions, geocoding, routes-api] metadata: {"clawdbot":{"emoji":"🗺️","requires":{"env":["GOOGLE_API_KEY"],"python":["requests"]},"primaryEnv":"GOOGLE_API_KEY","secondaryEnv":["GOOGLE_MAPS_API_KEY"],"optionalEnv":["GOOGLE_MAPS_LANG"],"notes":"Requires the 'requests' Python package (pip install requests). No other external dependencies."}} allowed-tools: [exec] --- # Google Maps 🗺️ Google Maps integration powered by the Routes API. ## Requirements - `GOOGLE_API_KEY` environment variable - Enable in Google Cloud Console: Routes API, Places API, Geocoding API - Python package: `requests` (`pip install requests`) ## Configuration | Env Variable | Default | Description | |--------------|---------|-------------| | `GOOGLE_API_KEY` | - | Required. Your Google Maps API key | | `GOOGLE_MAPS_API_KEY` | - | Alternative to `GOOGLE_API_KEY` (fallback) | | `GOOGLE_MAPS_LANG` | `en` | Response language (en, he, ja, etc.) | Set in OpenClaw config: ```json { "env": { "GOOGLE_API_KEY": "AIza...", "GOOGLE_MAPS_LANG": "en" } } ``` ## Script Location ```bash python3 skills/google-maps/lib/map_helper.py <action> [options] ``` --- ## Actions ### distance - Calculate travel time ```bash python3 skills/google-maps/lib/map_helper.py distance "origin" "destination" [options] ``` **Options:** | Option | Values | Description | |--------|--------|-------------| | `--mode` | driving, walking, bicycling, transit | Travel mode (default: driving) | | `--depart` | now, +30m, +1h, 14:00, 2026-02-07 08:00 | Departure time | | `--arrive` | 14:00 | Arrival time (transit only) | | `--traffic` | best_guess, pessimistic, optimistic | Traffic model | | `--avoid` | tolls, highways, ferries | Comma-separated | **Examples:** ```bash python3 skills/google-maps/lib/map_helper.py distance "New York" "Boston" python3 skills/google-maps/lib/map_helper.py distance "Los Angeles" "San Francisco" --depart="+1h" python3 skills/google-maps/lib/map_helper.py distance "Chicago" "Detroit" --depart="08:00" --traffic=pessimistic python3 skills/google-maps/lib/map_helper.py distance "London" "Manchester" --mode=transit --arrive="09:00" python3 skills/google-maps/lib/map_helper.py distance "Paris" "Lyon" --avoid=tolls,highways ``` **Response:** ```json { "distance": "215.2 mi", "distance_meters": 346300, "duration": "3 hrs 45 mins", "duration_seconds": 13500, "static_duration": "3 hrs 30 mins", "duration_in_traffic": "3 hrs 45 mins" } ``` --- ### directions - Turn-by-turn route ```bash python3 skills/google-maps/lib/map_helper.py directions "origin" "destination" [options] ``` **Additional options (beyond distance):** | Option | Description | |--------|-------------| | `--alternatives` | Return multiple routes | | `--waypoints` | Intermediate stops (pipe-separated) | | `--optimize` | Optimize waypoint order (TSP) | **Examples:** ```bash python3 skills/google-maps/lib/map_helper.py directions "New York" "Washington DC" python3 skills/google-maps/lib/map_helper.py directions "San Francisco" "Los Angeles" --alternatives python3 skills/google-maps/lib/map_helper.py directions "Miami" "Orlando" --waypoints="Fort Lauderdale|West Palm Beach" --optimize ``` **Response includes:** summary, labels, duration, static_duration, warnings, steps[], optimized_waypoint_order --- ### matrix - Distance matrix Calculate distances between multiple origins and destinations: ```bash python3 skills/google-maps/lib/map_helper.py matrix "orig1|orig2" "dest1|dest2" ``` **Example:** ```bash python3 skills/google-maps/lib/map_helper.py matrix "New York|Boston" "Philadelphia|Washington DC" ``` **Response:** ```json { "origins": ["New York", "Boston"], "destinations": ["Philadelphia", "Washington DC"], "results": [ {"origin_index": 0, "destination_index": 0, "distance": "97 mi", "duration": "1 hr 45 mins"}, {"origin_index": 0, "destination_index": 1, "distance": "225 mi", "duration": "4 hrs 10 mins"} ] } ``` --- ### geocode - Address to coordinates ```bash python3 skills/google-maps/lib/map_helper.py geocode "1600 Amphitheatre Parkway, Mountain View, CA" python3 skills/google-maps/lib/map_helper.py geocode "10 Downing Street, London" ``` ### reverse - Coordinates to address ```bash python3 skills/google-maps/lib/map_helper.py reverse 40.7128 -74.0060 # New York City python3 skills/google-maps/lib/map_helper.py reverse 51.5074 -0.1278 # London ``` --- ### search - Find places ```bash python3 skills/google-maps/lib/map_helper.py search "coffee near Times Square" python3 skills/google-maps/lib/map_helper.py search "pharmacy in San Francisco" --open ``` ### details - Place information ```bash python3 skills/google-maps/lib/map_helper.py details "<place_id>" ``` --- ## Traffic Models | Model | Use Case | |-------|----------| | `best_guess` | Default balanced estimate | | `pessimistic` | Important meetings (worst-case) | | `optimistic` | Best-case scenario | --- ## Regional Notes Some features may not be available in all countries: | Feature | Availability | |---------|--------------| | `--fuel-efficient` | US, EU, select countries | | `--shorter` | Limited availability | | `--mode=two_wheeler` | Asia, select countries | Check [Google Maps coverage](https://developers.google.com/maps/coverage) for details. --- ## Multilingual Support Works with addresses in any language: ```bash # Hebrew python3 skills/google-maps/lib/map_helper.py distance "תל אביב" "ירושלים" python3 skills/google-maps/lib/map_helper.py geocode "דיזנגוף 50, תל אביב" # Japanese python3 skills/google-maps/lib/map_helper.py distance "東京" "大阪" # Arabic python3 skills/google-maps/lib/map_helper.py distance "دبي" "أبو ظبي" ``` **Language configuration:** 1. Set default via env: `GOOGLE_MAPS_LANG=he` (persists) 2. Override per-request: `--lang=ja` ```bash # Set Hebrew as default in OpenClaw config GOOGLE_MAPS_LANG=he # Override for specific request python3 skills/google-maps/lib/map_helper.py distance "Tokyo" "Osaka" --lang=ja ``` --- ## Help ```bash python3 skills/google-maps/lib/map_helper.py help ```

path: lib/map_helper.py
content: #!/usr/bin/env python3
"""
Google Maps v3.1 - Next-Gen Maps Integration for OpenClaw
Author: Leo 🦁
Updated: 2026-02-06

Migrated to the NEW Routes API (replacing deprecated Distance Matrix & Directions APIs)

Features:
- Routes API (computeRoutes) - Modern directions with traffic
- Route Matrix API (computeRouteMatrix) - Distance/duration matrix
- Places API - Search and details
- Geocoding API - Address ↔ coordinates
- Future departure time prediction
- Traffic models (best_guess, pessimistic, optimistic)
- Route modifiers (avoid tolls, highways, ferries)
- Multiple travel modes (drive, walk, bicycle, transit, two_wheeler)
- Fuel-efficient and shorter-distance route options
- Waypoint optimization (TSP)
- Transit preferences (arrival time, route types)

APIs Used:
- Routes API v2 (NEW) - for routes and distance matrix
- Places API - for search and details
- Geocoding API - for address conversion
"""

import requests
import sys
import json
import os
from datetime import datetime, timedelta, timezone
import re


class GoogleMapsElite:
    """Google Maps integration for OpenClaw - v3.0 with Routes API."""
    
    # Default language: check env var, fall back to English
    DEFAULT_LANG = os.getenv("GOOGLE_MAPS_LANG", "en")
    
    def __init__(self):
        self.[REDACTED_SECRET]"GOOGLE_API_KEY") or os.getenv("GOOGLE_MAPS_API_KEY")
        self.maps_base = "https://maps.googleapis.com/maps/api"
        self.routes_base = "https://routes.googleapis.com"
        self._current_lang = self.DEFAULT_LANG  # Track current request language
    
    def _validate_key(self):
        if not self.[REDACTED_SECRET] {"error": "Missing API key. Set GOOGLE_API_KEY environment variable."}
        return None
    
    def _parse_time(self, time_str):
        """
        Parse time string to RFC 3339 timestamp for Routes API.
        Supports:
        - "now" → current time
        - "+30m", "+1h", "+2h30m" → relative time
        - "14:00", "14:30" → today at that time (or tomorrow if passed)
        - "2026-02-06 14:00" → specific datetime
        - Unix timestamp (integer)
        
        Returns RFC 3339 format: "2026-02-06T14:00:00Z"
        """
        if time_str is None or time_str == "now":
            return None  # Routes API uses current time by default
        
        now = datetime.now(timezone.utc)
        local_now = datetime.now()
        
        # Already a timestamp
        if isinstance(time_str, int) or (isinstance(time_str, str) and time_str.isdigit()):
            ts = int(time_str)
            dt = datetime.fromtimestamp(ts, timezone.utc)
            return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
        
        # Relative time: +30m, +1h, +2h30m
        relative_match = re.match(r'^\+(\d+h)?(\d+m)?$', time_str.replace(' ', ''))
        if relative_match:
            hours = int(relative_match.group(1)[:-1]) if relative_match.group(1) else 0
            minutes = int(relative_match.group(2)[:-1]) if relative_match.group(2) else 0
            future = now + timedelta(hours=hours, minutes=minutes)
            return future.strftime("%Y-%m-%dT%H:%M:%SZ")
        
        # Time only: 14:00, 14:30 (local time)
        time_only_match = re.match(r'^(\d{1,2}):(\d{2})$', time_str)
        if time_only_match:
            hour, minute = int(time_only_match.group(1)), int(time_only_match.group(2))
            target = local_now.replace(hour=hour, minute=minute, second=0, microsecond=0)
            if target <= local_now:
                target += timedelta(days=1)  # Tomorrow if time has passed
            # Convert to UTC
            target_utc = target.astimezone(timezone.utc)
            return target_utc.strftime("%Y-%m-%dT%H:%M:%SZ")
        
        # Full datetime: 2026-02-06 14:00 (local time)
        try:
            dt = datetime.strptime(time_str, "%Y-%m-%d %H:%M")
            dt_utc = dt.astimezone(timezone.utc)
            return dt_utc.strftime("%Y-%m-%dT%H:%M:%SZ")
        except ValueError:
            pass
        
        # ISO format with timezone
        try:
            dt = datetime.fromisoformat(time_str.replace('Z', '+00:00'))
            return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
        except ValueError:
            pass
        
        return None  # Fallback to current time
    
    def _format_duration(self, duration_str):
        """Convert '1234s' to human readable format."""
        if not duration_str:
            return None
        lang = getattr(self, '_current_lang', self.DEFAULT_LANG)
        seconds = int(duration_str.rstrip('s'))
        hours = seconds // 3600
        minutes = (seconds % 3600) // 60
        
        if lang == "he":
            if hours > 0:
                return f"{hours} שעות {minutes} דקות" if minutes > 0 else f"{hours} שעות"
            return f"{minutes} דקות"
        else:
            # English/international
            if hours > 0:
                return f"{hours} hr {minutes} min" if minutes > 0 else f"{hours} hr"
            return f"{minutes} min"
    
    def _format_distance(self, meters):
        """Convert meters to km or m."""
        lang = getattr(self, '_current_lang', self.DEFAULT_LANG)
        if lang == "he":
            if meters >= 1000:
                return f"{meters/1000:.1f} ק\"מ"
            return f"{meters} מ'"
        else:
            # English/international - use km
            if meters >= 1000:
                return f"{meters/1000:.1f} km"
            return f"{meters} m"
    
    def _travel_mode(self, mode):
        """Convert user-friendly mode to Routes API enum."""
        modes = {
            'driving': 'DRIVE',
            'drive': 'DRIVE',
            'walking': 'WALK',
            'walk': 'WALK',
            'bicycling': 'BICYCLE',
            'bicycle': 'BICYCLE',
            'bike': 'BICYCLE',
            'transit': 'TRANSIT',
            'two_wheeler': 'TWO_WHEELER',
            'motorcycle': 'TWO_WHEELER',
        }
        return modes.get(mode.lower(), 'DRIVE')
    
    def _routing_preference(self, traffic_mode):
        """Get routing preference based on traffic mode."""
        if traffic_mode in ['optimistic', 'pessimistic']:
            return 'TRAFFIC_AWARE_OPTIMAL'  # Required for traffic models
        return 'TRAFFIC_AWARE'  # Good balance of speed and accuracy
    
    def _traffic_model(self, model):
        """Convert user-friendly traffic model to API enum."""
        models = {
            'best_guess': 'BEST_GUESS',
            'optimistic': 'OPTIMISTIC',
            'pessimistic': 'PESSIMISTIC',
        }
        return models.get(model.lower(), 'BEST_GUESS') if model else None

    # ==================== GEOCODING ====================
    
    def geocode(self, address, language=None):
        """Convert address to coordinates (forward geocoding)."""
        language = language or self.DEFAULT_LANG
        error = self._validate_key()
        if error:
            return error
        
        url = f"{self.maps_base}/geocode/json"
        params = {
            "address": address,
            "key": self.api_key,
            "language": language
        }
        
        res = requests.get(url, params=params).json()
        
        if res.get("status") == "OK" and res.get("results"):
            result = res["results"][0]
            location = result["geometry"]["location"]
            return {
                "address": result["formatted_address"],
                "lat": location["lat"],
                "lng": location["lng"],
                "place_id": result.get("place_id"),
                "location_type": result["geometry"].get("location_type")
            }
        
        return {"error": f"Geocoding failed: {res.get('status')}"}
    
    def reverse_geocode(self, lat, lng, language=None):
        """Convert coordinates to address (reverse geocoding)."""
        language = language or self.DEFAULT_LANG
        error = self._validate_key()
        if error:
            return error
        
        url = f"{self.maps_base}/geocode/json"
        params = {
            "latlng": f"{lat},{lng}",
            "key": self.api_key,
            "language": language
        }
        
        res = requests.get(url, params=params).json()
        
        if res.get("status") == "OK" and res.get("results"):
            result = res["results"][0]
            return {
                "address": result["formatted_address"],
                "place_id": result.get("place_id"),
                "types": result.get("types", [])
            }
        
        return {"error": f"Reverse geocoding failed: {res.get('status')}"}

    # ==================== PLACES ====================
    
    def search(self, query, location="32.0684,34.7905", radius=2000, open_now=False, language=None):
        """Search for places by text query."""
        language = language or self.DEFAULT_LANG
        error = self._validate_key()
        if error:
            return error
        
        url = f"{self.maps_base}/place/textsearch/json"
        params = {
            "query": query,
            "location": location,
            "radius": radius,
            "key": self.api_key,
            "language": language
        }
        if open_now:
            params["opennow"] = "true"
        
        res = requests.get(url, params=params).json()
        results = res.get("results", [])[:5]
        
        for place in results:
            if place.get("photos"):
                photo_ref = place["photos"][0]["photo_reference"]
                place["photo_url"] = f"https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photoreference={photo_ref}&key={self.api_key}"
        
        return results
    
    def details(self, place_id, language=None):
        """Get detailed information about a place."""
        language = language or self.DEFAULT_LANG
        error = self._validate_key()
        if error:
            return error
        
        url = f"{self.maps_base}/place/details/json"
        params = {
            "place_id": place_id,
            "key": self.api_key,
            "language": language,
            "fields": "name,opening_hours,formatted_phone_number,rating,formatted_address,reviews,url,price_level,photos,vicinity,website"
        }
        
        res = requests.get(url, params=params).json().get("result", {})
        
        if res.get("photos"):
            photo_ref = res["photos"][0]["photo_reference"]
            res["photo_url"] = f"https://maps.googleapis.com/maps/api/place/photo?maxwidth=800&photoreference={photo_ref}&key={self.api_key}"
        
        return res

    # ==================== ROUTES API - DISTANCE ====================
    
    def _resolve_location(self, location_str):
        """
        Resolve a location string to lat/lng.
        Accepts: address string, "lat,lng", or place_id:xxx
        """
        # Check if it's already coordinates
        coord_match = re.match(r'^(-?\d+\.?\d*),\s*(-?\d+\.?\d*)$', location_str.strip())
        if coord_match:
            return {
                "location": {
                    "latLng": {
                        "latitude": float(coord_match.group(1)),
                        "longitude": float(coord_match.group(2))
                    }
                }
            }
        
        # Check if it's a place_id
        if location_str.startswith("place_id:"):
            return {"placeId": location_str[9:]}
        
        # Geocode the address
        geo = self.geocode(location_str)
        if "error" in geo:
            return None
        
        return {
            "location": {
                "latLng": {
                    "latitude": geo["lat"],
                    "longitude": geo["lng"]
                }
            }
        }
    
    def distance(self, origin, destination, mode="driving", language=None,
                 departure_time=None, arrival_time=None, traffic_model=None, avoid=None):
        """
        Calculate distance and duration between two points using Routes API.
        
        Args:
            origin: Starting point (address, coordinates, or place_id:xxx)
            destination: End point
            mode: Travel mode - driving, walking, bicycling, transit, two_wheeler
            departure_time: When to leave - "now", "+30m", "+1h", "14:00", "2026-02-06 14:00"
            arrival_time: When to arrive (transit only)
            traffic_model: "best_guess" (default), "pessimistic", "optimistic"
            avoid: Comma-separated - "tolls", "highways", "ferries"
        
        Returns:
            dict with distance, duration, duration_in_traffic
        """
        language = language or self.DEFAULT_LANG
        self._current_lang = language  # Store for formatting functions
        error = self._validate_key()
        if error:
            return error
        
        # Resolve locations
        origin_wp = self._resolve_location(origin)
        dest_wp = self._resolve_location(destination)
        
        if not origin_wp or not dest_wp:
            return {"error": "Could not resolve origin or destination address"}
        
        # Build request
        travel_mode = self._travel_mode(mode)
        
        # For computeRoutes, origin/destination are direct Waypoint objects
        request_body = {
            "origin": origin_wp,
            "destination": dest_wp,
            "travelMode": travel_mode,
            "languageCode": language,
            "units": "METRIC"
        }
        
        # Routing preference (only for DRIVE/TWO_WHEELER)
        if travel_mode in ['DRIVE', 'TWO_WHEELER']:
            request_body["routingPreference"] = self._routing_preference(traffic_model)
            
            # Traffic model (only with TRAFFIC_AWARE_OPTIMAL)
            if traffic_model and traffic_model.lower() in ['optimistic', 'pessimistic']:
                request_body["trafficModel"] = self._traffic_model(traffic_model)
        
        # Departure time
        if departure_time:
            parsed = self._parse_time(departure_time)
            if parsed:
                request_body["departureTime"] = parsed
        
        # Arrival time (transit only)
        if arrival_time and travel_mode == "TRANSIT":
            parsed = self._parse_time(arrival_time)
            if parsed:
                request_body["arrivalTime"] = parsed
                request_body.pop("departureTime", None)
        
        # Route modifiers
        if avoid:
            modifiers = {}
            avoid_list = [a.strip().lower() for a in avoid.split(",")]
            if "tolls" in avoid_list:
                modifiers["avoidTolls"] = True
            if "highways" in avoid_list:
                modifiers["avoidHighways"] = True
            if "ferries" in avoid_list:
                modifiers["avoidFerries"] = True
            if modifiers:
                request_body["routeModifiers"] = modifiers
        
        # Call Routes API
        url = f"{self.routes_base}/directions/v2:computeRoutes"
        headers = {
            "Content-Type": "application/json",
            "X-Goog-Api-Key": self.api_key,
            "X-Goog-FieldMask": "routes.duration,routes.staticDuration,routes.distanceMeters,routes.legs.startLocation,routes.legs.endLocation"
        }
        
        response = requests.post(url, headers=headers, json=request_body)
        
        if response.status_code != 200:
            return {"error": f"API error: {response.status_code}", "details": response.text}
        
        data = response.json()
        
        if not data.get("routes"):
            return {"error": "No route found"}
        
        route = data["routes"][0]
        
        result = {
            "distance": self._format_distance(route.get("distanceMeters", 0)),
            "distance_meters": route.get("distanceMeters", 0),
        }
        
        # Duration (with traffic for DRIVE)
        if route.get("duration"):
            result["duration"] = self._format_duration(route["duration"])
            result["duration_seconds"] = int(route["duration"].rstrip('s'))
        
        # Static duration (without traffic)
        if route.get("staticDuration"):
            result["static_duration"] = self._format_duration(route["staticDuration"])
            result["static_duration_seconds"] = int(route["staticDuration"].rstrip('s'))
        
        # If traffic-aware, duration already includes traffic
        if travel_mode in ['DRIVE', 'TWO_WHEELER'] and route.get("duration"):
            result["duration_in_traffic"] = result["duration"]
            result["duration_in_traffic_seconds"] = result["duration_seconds"]
        
        # Add departure time info
        if departure_time and departure_time != "now":
            result["departure_time"] = departure_time
        
        return result

    # ==================== ROUTES API - DIRECTIONS ====================
    
    def directions(self, origin, destination, mode="driving", language=None,
                   departure_time=None, arrival_time=None, alternatives=False,
                   avoid=None, waypoints=None, optimize_waypoints=False,
                   fuel_efficient=False, shorter_distance=False):
        """
        Get full directions with route steps using Routes API.
        
        Args:
            origin: Starting point
            destination: End point
            mode: driving, walking, bicycling, transit, two_wheeler
            departure_time: When to leave
            arrival_time: When to arrive (transit only)
            alternatives: Return alternative routes
            avoid: tolls, highways, ferries
            waypoints: List of intermediate stops
            optimize_waypoints: Optimize waypoint order (TSP)
            fuel_efficient: Request fuel-efficient route
            shorter_distance: Request shorter distance route
        
        Returns:
            Route information with steps, duration, distance
        """
        language = language or self.DEFAULT_LANG
        self._current_lang = language  # Store for formatting functions
        error = self._validate_key()
        if error:
            return error
        
        # Resolve locations
        origin_wp = self._resolve_location(origin)
        dest_wp = self._resolve_location(destination)
        
        if not origin_wp or not dest_wp:
            return {"error": "Could not resolve origin or destination address"}
        
        travel_mode = self._travel_mode(mode)
        
        # For computeRoutes, origin/destination are direct Waypoint objects
        request_body = {
            "origin": origin_wp,
            "destination": dest_wp,
            "travelMode": travel_mode,
            "languageCode": language,
            "units": "METRIC"
        }
        
        # Routing preference
        if travel_mode in ['DRIVE', 'TWO_WHEELER']:
            request_body["routingPreference"] = "TRAFFIC_AWARE"
        
        # Alternatives
        if alternatives and not waypoints:
            request_body["computeAlternativeRoutes"] = True
        
        # Departure time
        if departure_time:
            parsed = self._parse_time(departure_time)
            if parsed:
                request_body["departureTime"] = parsed
        
        # Arrival time (transit only)
        if arrival_time and travel_mode == "TRANSIT":
            parsed = self._parse_time(arrival_time)
            if parsed:
                request_body["arrivalTime"] = parsed
                request_body.pop("departureTime", None)
        
        # Route modifiers
        modifiers = {}
        if avoid:
            avoid_list = [a.strip().lower() for a in avoid.split(",")]
            if "tolls" in avoid_list:
                modifiers["avoidTolls"] = True
            if "highways" in avoid_list:
                modifiers["avoidHighways"] = True
            if "ferries" in avoid_list:
                modifiers["avoidFerries"] = True
        if modifiers:
            request_body["routeModifiers"] = modifiers
        
        # Waypoints (intermediates are direct Waypoint objects for computeRoutes)
        if waypoints:
            intermediates = []
            wp_list = waypoints if isinstance(waypoints, list) else waypoints.split("|")
            for wp in wp_list:
                resolved = self._resolve_location(wp.strip())
                if resolved:
                    intermediates.append(resolved)
            if intermediates:
                request_body["intermediates"] = intermediates
                if optimize_waypoints:
                    request_body["optimizeWaypointOrder"] = True
        
        # Reference routes
        if fuel_efficient or shorter_distance:
            refs = []
            if fuel_efficient:
                refs.append("FUEL_EFFICIENT")
            if shorter_distance:
                refs.append("SHORTER_DISTANCE")
            request_body["requestedReferenceRoutes"] = refs
        
        # Call Routes API
        url = f"{self.routes_base}/directions/v2:computeRoutes"
        
        # Build field mask
        field_mask = "routes.duration,routes.staticDuration,routes.distanceMeters,routes.description,routes.routeLabels,routes.legs.steps.navigationInstruction,routes.legs.steps.distanceMeters,routes.legs.steps.staticDuration,routes.legs.steps.transitDetails,routes.legs.localizedValues,routes.warnings"
        
        # Add optimized waypoint index if optimizing
        if optimize_waypoints:
            field_mask += ",routes.optimizedIntermediateWaypointIndex"
        
        headers = {
            "Content-Type": "application/json",
            "X-Goog-Api-Key": self.api_key,
            "X-Goog-FieldMask": field_mask
        }
        
        response = requests.post(url, headers=headers, json=request_body)
        
        if response.status_code != 200:
            return {"error": f"API error: {response.status_code}", "details": response.text}
        
        data = response.json()
        
        if not data.get("routes"):
            return {"error": "No route found"}
        
        routes = []
        for route in data["routes"]:
            route_info = {
                "distance": self._format_distance(route.get("distanceMeters", 0)),
                "distance_meters": route.get("distanceMeters", 0),
            }
            
            # Description
            if route.get("description"):
                route_info["summary"] = route["description"]
            
            # Labels (DEFAULT_ROUTE, FUEL_EFFICIENT, etc.)
            if route.get("routeLabels"):
                route_info["labels"] = route["routeLabels"]
            
            # Duration
            if route.get("duration"):
                route_info["duration"] = self._format_duration(route["duration"])
                route_info["duration_seconds"] = int(route["duration"].rstrip('s'))
            
            if route.get("staticDuration"):
                route_info["static_duration"] = self._format_duration(route["staticDuration"])
            
            # Warnings
            if route.get("warnings"):
                route_info["warnings"] = route["warnings"]
            
            # Optimized waypoint order
            if route.get("optimizedIntermediateWaypointIndex"):
                route_info["optimized_waypoint_order"] = route["optimizedIntermediateWaypointIndex"]
            
            # Steps
            steps = []
            for leg in route.get("legs", []):
                # Leg-level info
                if leg.get("localizedValues"):
                    lv = leg["localizedValues"]
                    if lv.get("staticDuration") and not route_info.get("static_duration"):
                        route_info["static_duration"] = lv["staticDuration"].get("text")
                    if lv.get("distance") and not route_info.get("distance"):
                        route_info["distance"] = lv["distance"].get("text")
                
                for step in leg.get("steps", []):
                    step_info = {}
                    
                    # Navigation instruction
                    if step.get("navigationInstruction"):
                        nav = step["navigationInstruction"]
                        step_info["instruction"] = nav.get("instructions", "")
                        if nav.get("maneuver"):
                            step_info["maneuver"] = nav["maneuver"]
                    
                    # Distance
                    if step.get("distanceMeters"):
                        step_info["distance"] = self._format_distance(step["distanceMeters"])
                    
                    # Duration
                    if step.get("staticDuration"):
                        step_info["duration"] = self._format_duration(step["staticDuration"])
                    
                    # Transit details
                    if step.get("transitDetails"):
                        td = step["transitDetails"]
                        transit_info = {}
                        if td.get("transitLine"):
                            line = td["transitLine"]
                            transit_info["line"] = line.get("nameShort") or line.get("name", "")
                            if line.get("vehicle"):
                                transit_info["vehicle"] = line["vehicle"].get("name", {}).get("text", "")
                        if td.get("stopDetails"):
                            sd = td["stopDetails"]
                            if sd.get("departureStop"):
                                transit_info["departure_stop"] = sd["departureStop"].get("name", "")
                            if sd.get("arrivalStop"):
                                transit_info["arrival_stop"] = sd["arrivalStop"].get("name", "")
                        if td.get("stopCount"):
                            transit_info["num_stops"] = td["stopCount"]
                        step_info["transit"] = transit_info
                    
                    if step_info:
                        steps.append(step_info)
            
            route_info["steps"] = steps
            routes.append(route_info)
        
        return routes[0] if not alternatives else routes

    # ==================== ROUTE MATRIX ====================
    
    def matrix(self, origins, destinations, mode="driving", departure_time=None, avoid=None):
        """
        Calculate distance/duration matrix for multiple origins and destinations.
        
        Args:
            origins: List of origin addresses/coordinates
            destinations: List of destination addresses/coordinates
            mode: Travel mode
            departure_time: When to depart
            avoid: Route modifiers
        
        Returns:
            Matrix of distances and durations
        """
        error = self._validate_key()
        if error:
            return error
        
        # Resolve all locations
        origin_waypoints = []
        for o in origins:
            resolved = self._resolve_location(o)
            if resolved:
                origin_waypoints.append({"waypoint": resolved})
        
        dest_waypoints = []
        for d in destinations:
            resolved = self._resolve_location(d)
            if resolved:
                dest_waypoints.append({"waypoint": resolved})
        
        if not origin_waypoints or not dest_waypoints:
            return {"error": "Could not resolve all locations"}
        
        travel_mode = self._travel_mode(mode)
        
        request_body = {
            "origins": origin_waypoints,
            "destinations": dest_waypoints,
            "travelMode": travel_mode,
        }
        
        # Routing preference
        if travel_mode in ['DRIVE', 'TWO_WHEELER']:
            request_body["routingPreference"] = "TRAFFIC_AWARE"
        
        # Departure time
        if departure_time:
            parsed = self._parse_time(departure_time)
            if parsed:
                # Note: For matrix, we'd need to add this per-origin or as extraComputations
                pass
        
        # Call Route Matrix API
        url = f"{self.routes_base}/distanceMatrix/v2:computeRouteMatrix"
        headers = {
            "Content-Type": "application/json",
            "X-Goog-Api-Key": self.api_key,
            "X-Goog-FieldMask": "originIndex,destinationIndex,duration,distanceMeters,status,condition"
        }
        
        response = requests.post(url, headers=headers, json=request_body)
        
        if response.status_code != 200:
            return {"error": f"API error: {response.status_code}", "details": response.text}
        
        data = response.json()
        
        # Format results as matrix
        results = []
        for element in data:
            if element.get("condition") == "ROUTE_EXISTS":
                results.append({
                    "origin_index": element.get("originIndex", 0),
                    "destination_index": element.get("destinationIndex", 0),
                    "distance": self._format_distance(element.get("distanceMeters", 0)),
                    "distance_meters": element.get("distanceMeters", 0),
                    "duration": self._format_duration(element.get("duration")),
                    "duration_seconds": int(element.get("duration", "0s").rstrip('s'))
                })
            else:
                results.append({
                    "origin_index": element.get("originIndex", 0),
                    "destination_index": element.get("destinationIndex", 0),
                    "error": element.get("condition", "UNKNOWN")
                })
        
        return {
            "origins": origins,
            "destinations": destinations,
            "results": results
        }


def print_help():
    """Print usage information."""
    help_text = """
Google Maps v3.1 (Routes API) - Usage:

═══════════════════════════════════════════════════════════════
DISTANCE & TRAVEL TIME
═══════════════════════════════════════════════════════════════

  python map_helper.py distance "origin" "destination" [options]
  
  Options:
    --mode=driving|walking|bicycling|transit|two_wheeler
    --depart="now"|"+30m"|"+1h"|"14:00"|"2026-02-06 14:00"
    --arrive="14:00" (transit only)
    --traffic=best_guess|pessimistic|optimistic
    --avoid=tolls|highways|ferries (comma-separated)
  
  Examples:
    python map_helper.py distance "Tel Aviv" "Jerusalem"
    python map_helper.py distance "Tel Aviv" "Jerusalem" --depart="+1h"
    python map_helper.py distance "Home" "Work" --depart="08:00" --traffic=pessimistic
    python map_helper.py distance "A" "B" --mode=transit --arrive="09:00"
    python map_helper.py distance "A" "B" --avoid=tolls,highways

═══════════════════════════════════════════════════════════════
FULL DIRECTIONS (Turn-by-Turn)
═══════════════════════════════════════════════════════════════

  python map_helper.py directions "origin" "destination" [options]
  
  Options (same as distance, plus):
    --alternatives       Get multiple route options
    --waypoints="A|B|C"  Intermediate stops
    --optimize           Optimize waypoint order (TSP)
    --fuel-efficient     Request fuel-efficient route
    --shorter            Request shorter distance route

  Examples:
    python map_helper.py directions "Tel Aviv" "Jerusalem"
    python map_helper.py directions "A" "B" --alternatives
    python map_helper.py directions "A" "D" --waypoints="B|C" --optimize

═══════════════════════════════════════════════════════════════
DISTANCE MATRIX (Multiple Origins/Destinations)
═══════════════════════════════════════════════════════════════

  python map_helper.py matrix "orig1|orig2" "dest1|dest2" [options]

  Example:
    python map_helper.py matrix "Tel Aviv|Haifa" "Jerusalem|Eilat"

═══════════════════════════════════════════════════════════════
GEOCODING
═══════════════════════════════════════════════════════════════

  python map_helper.py geocode "Dizengoff 50, Tel Aviv"
  python map_helper.py reverse 32.0684 34.7905

═══════════════════════════════════════════════════════════════
PLACES SEARCH
═══════════════════════════════════════════════════════════════

  python map_helper.py search "coffee near Dizengoff" [--open] [--lang=en]
  python map_helper.py details "<place_id>"

═══════════════════════════════════════════════════════════════
HELP
═══════════════════════════════════════════════════════════════

  python map_helper.py help

"""
    print(help_text)


if __name__ == "__main__":
    if len(sys.argv) < 2 or sys.argv[1] == "help":
        print_help()
        sys.exit(0)
    
    action = sys.argv[1]
    elite = GoogleMapsElite()
    
    # Parse optional arguments
    def get_arg(prefix, default=None):
        for arg in sys.argv:
            if arg.startswith(f"--{prefix}="):
                return arg.split("=", 1)[1]
        return default
    
    def has_flag(flag):
        return f"--{flag}" in sys.argv
    
    lang = get_arg("lang")  # None = use DEFAULT_LANG from env or "en"
    
    result = None
    
    if action == "search" and len(sys.argv) >= 3:
        result = elite.search(sys.argv[2], open_now=has_flag("open"), language=lang)
    
    elif action == "details" and len(sys.argv) >= 3:
        result = elite.details(sys.argv[2], language=lang)
    
    elif action == "distance" and len(sys.argv) >= 4:
        result = elite.distance(
            origin=sys.argv[2],
            destination=sys.argv[3],
            mode=get_arg("mode", "driving"),
            language=lang,
            departure_time=get_arg("depart"),
            arrival_time=get_arg("arrive"),
            traffic_model=get_arg("traffic"),
            avoid=get_arg("avoid")
        )
    
    elif action == "directions" and len(sys.argv) >= 4:
        result = elite.directions(
            origin=sys.argv[2],
            destination=sys.argv[3],
            mode=get_arg("mode", "driving"),
            language=lang,
            departure_time=get_arg("depart"),
            arrival_time=get_arg("arrive"),
            alternatives=has_flag("alternatives"),
            avoid=get_arg("avoid"),
            waypoints=get_arg("waypoints"),
            optimize_waypoints=has_flag("optimize"),
            fuel_efficient=has_flag("fuel-efficient"),
            shorter_distance=has_flag("shorter")
        )
    
    elif action == "matrix" and len(sys.argv) >= 4:
        origins = sys.argv[2].split("|")
        destinations = sys.argv[3].split("|")
        result = elite.matrix(
            origins=origins,
            destinations=destinations,
            mode=get_arg("mode", "driving"),
            departure_time=get_arg("depart"),
            avoid=get_arg("avoid")
        )
    
    elif action == "geocode" and len(sys.argv) >= 3:
        result = elite.geocode(sys.argv[2], language=lang)
    
    elif action == "reverse" and len(sys.argv) >= 4:
        result = elite.reverse_geocode(sys.argv[2], sys.argv[3], language=lang)
    
    else:
        print_help()
        sys.exit(1)
    
    print(json.dumps(result, ensure_ascii=False, indent=2))


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)