build outside api server layers

src/services/googlemap_api_service.py

@@ -0,0 +1,904 @@
+"""
+Google Maps API Service
+"""
+
+import requests
+from typing import List, Dict, Any, Optional, Tuple, Union
+from datetime import datetime, timedelta, timezone
+import numpy as np
+import polyline
+from agno.run import RunContext
+
+from src.infra.logger import get_logger
+
+logger = get_logger(__name__)
+
+MAX_LOCATIONS_PER_SIDE = 50
+
+
+def cleanup_str(key: str) -> str:
+    return key.strip('\'" ')
+
+def clean_dict_list_keys(data_list: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    if not isinstance(data_list, list):
+        # 為了安全，如果輸入不是列表，直接返回原始輸入或空列表
+        print(f"Warning: Input is not a list. Received type: {type(data_list)}")
+        return data_list
+
+    cleaned_list = []
+
+    for item in data_list:
+        if isinstance(item, dict):
+            cleaned_item = {}
+            for original_key, value in item.items():
+                new_key = cleanup_str(original_key)
+                cleaned_item[new_key] = value
+
+            cleaned_list.append(cleaned_item)
+        else:
+            cleaned_list.append(item)
+
+    return cleaned_list
+
+class GoogleMapAPIService:
+    def __init__(self, api_key: Optional[str] = None):
+        """
+        Initialize Google Maps API service
+
+        Args:
+            api_key: Google Maps API key (required)
+        """
+        # ✅ 改進: 更靈活的配置獲取
+        if api_key:
+            self.api_key = api_key
+        else:
+            import os
+            self.api_key = os.getenv("GOOGLE_MAPS_API_KEY")
+            try:
+                from src.infra.config import get_settings
+                settings = get_settings()
+                self.api_key = settings.google_maps_api_key
+            except (ImportError, AttributeError) as e:
+                raise e
+
+        if not self.api_key:
+            raise ValueError(
+                "Google Maps API key is required. "
+                "Set via parameter, config, or GOOGLE_MAPS_API_KEY env var"
+            )
+
+        # API endpoints
+        self.geolocation_url = "https://www.googleapis.com/geolocation/v1/geolocate"
+        self.places_text_search_url = "https://places.googleapis.com/v1/places:searchText"
+        self.compute_routes_url = "https://routes.googleapis.com/directions/v2:computeRoutes"
+        self.compute_route_matrix_url = "https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix"
+
+        logger.info("✅ Google Maps API service initialized")
+
+    # ========================================================================
+    # Geolocation
+    # ========================================================================
+
+    def current_location(self) -> Dict[str, Any]:
+        """
+        Get current location using Geolocation API
+
+        Returns:
+            Location info with lat/lng
+
+        Raises:
+            requests.RequestException: If API request fails
+        """
+        try:
+            response = requests.post(
+                self.geolocation_url,
+                params={"key": self.api_key},
+                headers={"Content-Type": "application/json"},
+                timeout=10
+            )
+            if not response.ok:
+                logger.error(f"❌ Geolocation API error: {response.text}")
+                response.raise_for_status()
+            data = response.json()
+
+            # ✅ 改進: 檢查響應有效性
+            if "location" not in data:
+                raise ValueError("Invalid geolocation response")
+
+            logger.debug(f"📍 Current location: {data['location']}")
+            return data
+
+        except requests.Timeout:
+            logger.error("⏰ Geolocation request timeout")
+            raise
+        except requests.RequestException as e:
+            logger.error(f"❌ Geolocation request failed: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"❌ Unexpected error in current_location: {e}")
+            raise
+
+    # ========================================================================
+    # Places API - Text Search (New API v1)
+    # ========================================================================
+
+    def text_search(
+        self,
+        query: str,
+        location: Optional[Dict[str, float]] = None,
+        radius: Optional[int] = None,
+        limit: int = 3,
+    ) -> List[Dict[str, Any]]:
+        """
+        Search for a place to get its coordinates and details.
+        Use this to convert a user's vague query (e.g., "Gas station", "Taipei 101") into precise lat/lng coordinates.
+
+        Args:
+            query: The search text (e.g., "Din Tai Fung", "Hospital").
+            location: Optional bias location {"lat": float, "lng": float}.
+            radius: Search radius in meters (optional).
+            limit: Max results to return (default 3).
+
+        Returns:
+            List[Dict]: A list of places found. Each item contains:
+            - name: str
+            - address: str
+            - location: {"lat": float, "lng": float} (CRITICAL for routing)
+            - place_id: str
+            - rating: float
+        """
+        request_body = {
+            "textQuery": query,
+            "maxResultCount": min(limit, 20)
+        }
+
+        if location and radius:
+            request_body["locationBias"] = {
+                "circle": {
+                    "center": {
+                        "latitude": location["lat"],
+                        "longitude": location["lng"]
+                    },
+                    "radius": float(radius)
+                }
+            }
+
+        headers = {
+            "Content-Type": "application/json",
+            "X-Goog-Api-Key": self.api_key,
+            "X-Goog-FieldMask": (
+                "places.id,"
+                "places.displayName,"
+                "places.formattedAddress,"
+                "places.location,"
+                "places.rating,"
+                "places.userRatingCount,"
+                "places.businessStatus,"
+                "places.currentOpeningHours,"
+                "places.userRatingCount,"
+            )
+        }
+
+        try:
+            logger.debug(f"🔍 Searching places: '{query}' (limit={limit})")
+
+            response = requests.post(
+                self.places_text_search_url,
+                json=request_body,
+                headers=headers,
+                timeout=10
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            places = data.get("places", [])
+
+            if not places:
+                logger.warning(f"⚠️ No places found for query: '{query}'")
+                return []
+
+            logger.info(f"✅ Found {len(places)} places for '{query}'")
+
+            standardized_places = []
+            for place in places:
+                standardized_places.append({
+                    "place_id": place.get("id"),
+                    "name": place.get("displayName", {}).get("text", "Unknown"),
+                    "address": place.get("formattedAddress", ""),
+                    "location": place.get("location", {}),
+                    "rating": place.get("rating"),
+                    "user_ratings_total": place.get("userRatingCount", 0),
+                    "business_status": place.get("businessStatus", "UNKNOWN"),
+                    "opening_hours": place.get("currentOpeningHours", {})
+                })
+
+            return standardized_places
+
+        except requests.Timeout:
+            logger.error("⏰ Places search timeout")
+            raise
+        except requests.RequestException as e:
+            logger.error(f"❌ Places search failed: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"❌ Unexpected error in text_search: {e}")
+            raise
+
+    # ========================================================================
+    # Routes API - Compute Routes
+    # ========================================================================
+
+    def _compute_routes(
+        self,
+        origin: Dict[str, Any],
+        destination: Dict[str, Any],
+        waypoints: Optional[List[Dict[str, float]]] = None,
+        travel_mode: str = "DRIVE",
+        routing_preference: str = "TRAFFIC_AWARE_OPTIMAL",
+        compute_alternative_routes: bool = False,
+        optimize_waypoint_order: bool = False,
+        departure_time: Optional[datetime] = None,
+        include_traffic_on_polyline: bool = True
+    ) -> Dict[str, Any]:
+        """
+        ✅ P0-1 & P0-3 修復: 正確的經緯度 + 完整的響應解析
+
+        Internal method to compute routes using Routes API v2
+
+        Args:
+            origin: Origin location dict with 'lat' and 'lng' keys
+            destination: Destination location dict with 'lat' and 'lng' keys
+            waypoints: Optional list of waypoint dicts with 'lat' and 'lng'
+            travel_mode: Travel mode (DRIVE, WALK, BICYCLE, TRANSIT)
+            routing_preference: Routing preference
+            compute_alternative_routes: Whether to compute alternatives
+            optimize_waypoint_order: Whether to optimize waypoint order
+            departure_time: Departure time as datetime object
+            include_traffic_on_polyline: Whether to include traffic info
+
+        Returns:
+            Parsed route information dict with:
+                - distance_meters: int
+                - duration_seconds: int
+                - encoded_polyline: str
+                - legs: List[Dict]
+                - optimized_waypoint_order: Optional[List[int]]
+
+        Raises:
+            ValueError: If route cannot be computed
+            requests.RequestException: If API request fails
+        """
+        # ✅ P0-1 修復: 正確使用 lng 而不是 lat
+        request_body = {
+            "origin": {
+                "location": {
+                    "latLng": {
+                        "latitude": origin["lat"],
+                        "longitude": origin["lng"]  # ✅ 修復: 原來是 origin["lat"]
+                    }
+                }
+            },
+            "destination": {
+                "location": {
+                    "latLng": {
+                        "latitude": destination["lat"],
+                        "longitude": destination["lng"]  # ✅ 修復: 原來是 destination["lat"]
+                    }
+                }
+            },
+            "travelMode": travel_mode,
+            "routingPreference": routing_preference,
+            "computeAlternativeRoutes": compute_alternative_routes,
+            "languageCode": "zh-TW",
+            "units": "METRIC"
+        }
+
+        # ✅ 添加中間點
+        if waypoints:
+            request_body["intermediates"] = [
+                {
+                    "location": {
+                        "latLng": {
+                            "latitude": wp["lat"],
+                            "longitude": wp["lng"]
+                        }
+                    }
+                }
+                for wp in waypoints
+            ]
+
+            if optimize_waypoint_order:
+                request_body["optimizeWaypointOrder"] = True
+
+        if departure_time:
+            if isinstance(departure_time, datetime):
+                request_body["departureTime"] = departure_time.isoformat()
+            elif departure_time == "now":
+                request_body["departureTime"] = datetime.now(timezone.utc).isoformat()
+
+        # ✅ Field Mask
+        field_mask_parts = [
+            "routes.duration",
+            "routes.distanceMeters",
+            "routes.polyline.encodedPolyline",
+            "routes.legs",
+            "routes.optimizedIntermediateWaypointIndex"
+        ]
+
+        if include_traffic_on_polyline:
+            field_mask_parts.extend([
+                "routes.travelAdvisory",
+                "routes.legs.travelAdvisory"
+            ])
+
+        field_mask = ",".join(field_mask_parts)
+
+        headers = {
+            "Content-Type": "application/json",
+            "X-Goog-Api-Key": self.api_key,
+            "X-Goog-FieldMask": field_mask
+        }
+
+        logger.debug(
+            f"🗺️ Computing route: {origin['lat']:.4f},{origin['lng']:.4f} → "
+            f"{destination['lat']:.4f},{destination['lng']:.4f} "
+            f"({len(waypoints) if waypoints else 0} waypoints)"
+        )
+
+        try:
+            response = requests.post(
+                self.compute_routes_url,
+                json=request_body,
+                headers=headers,
+                timeout=30  # ✅ 增加超時時間
+            )
+            if not response.ok:
+                logger.error(f"❌ Routes API error: {response.text}")
+            response.raise_for_status()
+            data = response.json()
+
+            # ✅ P0-3 修復: 完整解析 API 響應
+            if "routes" not in data or not data["routes"]:
+                logger.error("❌ No routes found in API response")
+                raise ValueError("No routes found")
+
+            route = data["routes"][0]  # 取第一條路線
+
+            # ✅ 解析距離
+            distance_meters = route.get("distanceMeters", 0)
+
+            # ✅ 解析時間 (格式: "300s")
+            duration_str = route.get("duration", "0s")
+            duration_seconds = int(duration_str.rstrip("s"))
+
+            # ✅ 解析 polyline
+            polyline_data = route.get("polyline", {})
+            encoded_polyline = polyline_data.get("encodedPolyline", "")
+
+            # ✅ 解析 legs
+            legs = route.get("legs", [])
+
+            # ✅ 解析優化後的順序 (如果有)
+            optimized_order = route.get("optimizedIntermediateWaypointIndex")
+
+            result = {
+                "distance_meters": distance_meters,
+                "duration_seconds": duration_seconds,
+                "encoded_polyline": encoded_polyline,
+                "legs": legs,
+                "optimized_waypoint_order": optimized_order
+            }
+
+            logger.debug(
+                f"✅ Route computed: {distance_meters}m, {duration_seconds}s"
+            )
+
+            return result
+
+        except requests.Timeout:
+            logger.error("⏰ Routes request timeout")
+            raise
+        except requests.RequestException as e:
+            logger.error(f"❌ Routes request failed: {e}")
+            raise
+        except (KeyError, ValueError) as e:
+            logger.error(f"❌ Failed to parse route response: {e}")
+            raise ValueError(f"Invalid route response: {e}")
+        except Exception as e:
+            logger.error(f"❌ Unexpected error in _compute_routes: {e}")
+            raise
+
+    # ========================================================================
+    # Polyline Helper
+    # ========================================================================
+
+    def _merge_polylines(self, poly_lines: List[str]) -> str:
+        """
+        Merge multiple encoded polylines into a single polyline
+
+        Args:
+            poly_lines: List of encoded polyline strings
+
+        Returns:
+            Merged encoded polyline string
+        """
+        if not poly_lines:
+            return ""
+
+        all_points = []
+        for pl in poly_lines:
+            if pl:  # ✅ 改進: 跳過空字符串
+                points = polyline.decode(pl)
+                all_points.extend(points)
+
+        return polyline.encode(all_points) if all_points else ""
+
+    # ========================================================================
+    # Multi-leg Route Computation
+    # ========================================================================
+
+    def compute_routes(
+            self,
+            place_points: List[Dict[str, float]],
+            start_time: Union[datetime, str],
+            stop_times: List[int],
+            travel_mode: Union[str, List[str]] = "DRIVE",
+            routing_preference: str = "TRAFFIC_AWARE_OPTIMAL"
+    ) -> Dict[str, Any]:
+        """
+        Compute a detailed multi-stop route. Supports MIXED travel modes.
+
+        Args:
+            place_points: Ordered list of locations. Min 2 points.
+            start_time: "now" or datetime object.
+            stop_times: List of stay durations (minutes).
+                        CRITICAL: Length must match len(place_points).
+                        e.g., [0, 60, 30, 0] means:
+                        - Start at P0 (stay 0)
+                        - Arrive P1 (stay 60) -> Depart P1
+                        - Arrive P2 (stay 30) -> Depart P2
+                        - Arrive P3 (End)
+            travel_mode: Single string or List of strings.
+            routing_preference: "TRAFFIC_AWARE_OPTIMAL" (ignored for non-DRIVE modes).
+
+        Returns:
+            Dict: Route summary.
+        """
+
+        if len(place_points) < 2:
+            raise ValueError("At least 2 places required for route computation")
+
+        # ✅ 強制驗證：stop_times 長度必須與地點數量一致，避免邏輯混亂
+        if len(stop_times) != len(place_points):
+            raise ValueError(
+                f"stop_times length ({len(stop_times)}) must match "
+                f"place_points length ({len(place_points)})"
+            )
+
+        num_legs = len(place_points) - 1
+
+        # 驗證 travel_mode 列表長度
+        if isinstance(travel_mode, list):
+            if len(travel_mode) != num_legs:
+                raise ValueError(f"travel_mode list length ({len(travel_mode)}) must match legs count ({num_legs})")
+
+        # 處理開始時間
+        if start_time == "now" or start_time is None:
+            start_time = datetime.now(timezone.utc)
+            current_time = datetime.now(timezone.utc)
+        elif isinstance(start_time, datetime):
+            current_time = start_time.astimezone(timezone.utc)
+        else:
+            raise ValueError(f"Invalid start_time type: {type(start_time)}")
+
+        legs_info = []
+        total_distance = 0
+        total_duration = 0
+        place_points = clean_dict_list_keys(place_points)
+
+        logger.debug(f"🚦 Computing route. Points: {len(place_points)}, Modes: {travel_mode}")
+
+        for i in range(num_legs):
+            origin = place_points[i]
+            destination = place_points[i + 1]
+
+            # 1. 決定當前模式
+            if isinstance(travel_mode, list):
+                current_mode = travel_mode[i].upper()
+            else:
+                current_mode = travel_mode.upper()
+
+            # 2. 決定 Traffic Preference
+            if current_mode in ["DRIVE", "TWO_WHEELER"]:
+                current_preference = None if routing_preference == "UNDRIVE" else routing_preference.upper()
+            else:
+                current_preference = None
+
+            departure_time = current_time if i > 0 else None
+
+            try:
+                route = self._compute_routes(
+                    origin=origin,
+                    destination=destination,
+                    waypoints=None,
+                    travel_mode=current_mode,
+                    routing_preference=current_preference,
+                    include_traffic_on_polyline=True,
+                    departure_time=departure_time
+                )
+
+                leg_distance = route["distance_meters"]
+                leg_duration = route["duration_seconds"]
+
+                total_distance += leg_distance
+                total_duration += leg_duration
+
+                legs_info.append({
+                    "from_index": i,
+                    "to_index": i + 1,
+                    "travel_mode": current_mode,
+                    "distance_meters": leg_distance,
+                    "duration_seconds": leg_duration,
+                    "departure_time": current_time.isoformat(),
+                    "polyline": route["encoded_polyline"]
+                })
+
+                current_time += timedelta(seconds=leg_duration)
+
+                stop_duration = stop_times[i + 1]
+
+                current_time += timedelta(minutes=stop_duration)
+
+            except Exception as e:
+                logger.error(f"❌ Leg {i + 1} computation failed: {e}")
+                raise e
+
+        return {
+            "total_distance_meters": total_distance,
+            "total_duration_seconds": total_duration,  # 純交通時間
+            "total_residence_time_minutes": sum(stop_times),  # 總停留時間
+            "total_time_seconds": int((current_time - start_time).total_seconds()),  # 總行程時間 (含交通+停留)
+            "start_time": start_time,
+            "end_time": current_time,
+            "stops": place_points,
+            "legs": legs_info,
+        }
+
+
+    # ========================================================================
+    # Distance Matrix API
+    # ========================================================================
+
+    def _compute_route_matrix(
+        self,
+        origins: List[Dict[str, float]],
+        destinations: List[Dict[str, float]],
+        travel_mode: str = "DRIVE",
+        routing_preference: str = "TRAFFIC_UNAWARE",
+        departure_time: Optional[datetime] = None
+    ) -> Dict[str, Any]:
+        """
+        Internal method to compute distance matrix
+
+        Args:
+            origins: List of origin location dicts
+            destinations: List of destination location dicts
+            travel_mode: Travel mode
+            routing_preference: Routing preference
+            departure_time: Departure time
+
+        Returns:
+            API response with distance matrix data
+
+        Raises:
+            requests.RequestException: If API request fails
+        """
+        request_body = {
+            "origins": [
+                {
+                    "waypoint": {
+                        "location": {
+                            "latLng": {
+                                "latitude": origin["lat"],
+                                "longitude": origin["lng"]
+                            }
+                        }
+                    }
+                }
+                for origin in origins
+            ],
+            "destinations": [
+                {
+                    "waypoint": {
+                        "location": {
+                            "latLng": {
+                                "latitude": dest["lat"],
+                                "longitude": dest["lng"]
+                            }
+                        }
+                    }
+                }
+                for dest in destinations
+            ],
+            "travelMode": travel_mode.upper(),
+            "routingPreference": routing_preference.upper()
+        }
+
+        # ✅ 添加 departure_time
+        if departure_time:
+            if isinstance(departure_time, datetime):
+                request_body["departureTime"] = departure_time.isoformat()
+            elif departure_time == "now":
+                request_body["departureTime"] = datetime.now(timezone.utc).isoformat()
+
+        field_mask = "originIndex,destinationIndex,distanceMeters,duration"
+
+        headers = {
+            "Content-Type": "application/json",
+            "X-Goog-Api-Key": self.api_key,
+            "X-Goog-FieldMask": field_mask
+        }
+
+        logger.debug(
+            f"📏 Computing route matrix: {len(origins)} × {len(destinations)}"
+        )
+
+        try:
+            response = requests.post(
+                self.compute_route_matrix_url,
+                json=request_body,
+                headers=headers,
+                timeout=30
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            if "error" in data:
+                raise ValueError(f"API Error: {data['error']}")
+
+            if isinstance(data, list):
+                return data
+            elif "results" in data:
+                return data["results"]
+            else:
+                # 兜底：返回空數組
+                logger.warning(f"⚠️ Unexpected Distance Matrix response format: {data.keys()}")
+                return []
+
+        except requests.Timeout:
+            logger.error("⏰ Route matrix request timeout")
+            raise
+        except requests.RequestException as e:
+            logger.error(f"❌ Route matrix request failed: {e}")
+            raise e
+        except Exception as e:
+            logger.error(f"❌ Unexpected error in _compute_route_matrix: {e}")
+            raise
+
+    def _get_max_elements(self, travel_mode: str, routing_preference: str) -> int:
+        """
+        Get max elements per request based on travel mode and preference
+
+        Args:
+            travel_mode: Travel mode
+            routing_preference: Routing preference
+
+        Returns:
+            Max elements allowed
+        """
+        if travel_mode.upper() == "TRANSIT":
+            return 100
+        if routing_preference and routing_preference.upper() == "TRAFFIC_AWARE_OPTIMAL":
+            return 100
+        return 625
+
+    def compute_route_matrix(
+        self,
+        origins: List[Dict[str, float]],
+        destinations: List[Dict[str, float]],
+        travel_mode: str = "DRIVE",
+        routing_preference: Optional[str] = None,
+        departure_time: Optional[datetime] = None,
+    ) -> Dict[str, np.ndarray]:
+        """
+        ✅ P1-1 修復: 正確調用 _compute_route_matrix
+
+        Compute distance and duration matrix between multiple locations
+
+        Args:
+            origins: List of origin location dicts with 'lat' and 'lng'
+            destinations: List of destination location dicts with 'lat' and 'lng'
+            travel_mode: Travel mode (DRIVE, WALK, BICYCLE, TRANSIT)
+            routing_preference: Routing preference (optional)
+            departure_time: Departure time as datetime object (optional)
+
+        Returns:
+            Dict with numpy arrays:
+                - duration_matrix: Duration in seconds (shape: O×D)
+                - distance_matrix: Distance in meters (shape: O×D)
+
+        Raises:
+            ValueError: If input is invalid
+            requests.RequestException: If API request fails
+        """
+        if not origins or not destinations:
+            raise ValueError("Origins and destinations cannot be empty")
+
+        max_elements = self._get_max_elements(travel_mode, routing_preference or "")
+
+        O_len, D_len = len(origins), len(destinations)
+        duration_matrix = np.full((O_len, D_len), -1, dtype=np.int32)
+        distance_matrix = np.full((O_len, D_len), -1, dtype=np.int32)
+
+        logger.info(
+            f"📊 Computing {O_len}×{D_len} matrix "
+            f"(max_elements={max_elements})"
+        )
+
+        # ✅ 分批處理
+        for o_start in range(0, O_len, MAX_LOCATIONS_PER_SIDE):
+            o_end = min(o_start + MAX_LOCATIONS_PER_SIDE, O_len)
+            origin_batch = origins[o_start:o_end]
+            origin_batch_size = len(origin_batch)
+
+            max_dest_batch_size = max(
+                1,
+                min(
+                    MAX_LOCATIONS_PER_SIDE,
+                    min(D_len, max_elements // origin_batch_size)
+                ),
+            )
+
+            for d_start in range(0, D_len, max_dest_batch_size):
+                d_end = min(d_start + max_dest_batch_size, D_len)
+                dest_batch = destinations[d_start:d_end]
+
+                try:
+                    elements = self._compute_route_matrix(
+                        origins=origin_batch,
+                        destinations=dest_batch,
+                        travel_mode=travel_mode,
+                        routing_preference=routing_preference or "TRAFFIC_UNAWARE",
+                        departure_time=departure_time,
+                    )
+
+                    if not elements:
+                        logger.warning(
+                            f"⚠️ No elements in batch "
+                            f"[{o_start}:{o_end}, {d_start}:{d_end}]"
+                        )
+                        continue
+
+                    for el in elements:
+                        oi = o_start + el["originIndex"]
+                        di = d_start + el["destinationIndex"]
+
+                        # ✅ 解析時間 (格式: "300s")
+                        duration_str = el.get("duration", "0s")
+                        duration_seconds = int(duration_str.rstrip("s"))
+
+                        # ✅ 解析距離
+                        distance_meters = el.get("distanceMeters", 0)
+
+                        duration_matrix[oi, di] = duration_seconds
+                        distance_matrix[oi, di] = distance_meters
+
+                except Exception as e:
+                    logger.error(
+                        f"❌ Failed to compute matrix batch "
+                        f"[{o_start}:{o_end}, {d_start}:{d_end}]: {e}"
+)
+                    raise e
+
+        logger.info(
+            f"✅ Route matrix computed: "
+            f"{np.sum(duration_matrix >= 0)} / {O_len * D_len} elements"
+        )
+
+        return {
+            "duration_matrix": duration_matrix,
+            "distance_matrix": distance_matrix,
+        }
+
+
+# ============================================================================
+# Usage Example
+# ============================================================================
+
+if __name__ == "__main__":
+    import os
+    from src.infra.config import get_settings
+    # Initialize service
+    setting = get_settings()
+    api_key = setting.google_maps_api_key
+    if not api_key:
+        print("❌ Please set GOOGLE_MAPS_API_KEY environment variable")
+        exit(1)
+
+    service = GoogleMapAPIService(api_key=api_key)
+
+    # Example 1: Current location
+    try:
+        print("\n" + "="*60)
+        print("Example 1: Current Location")
+        print("="*60)
+        location = service.current_location()
+        print(f"📍 Current: {location['location']}")
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+
+    # Example 2: Text search
+    try:
+        print("\n" + "="*60)
+        print("Example 2: Text Search")
+        print("="*60)
+        places = service.text_search(
+            query="台大醫院",
+            location={"lat": 25.0408, "lng": 121.5318},
+            radius=5000,
+            limit=3
+        )
+        for i, place in enumerate(places, 1):
+            print(f"{i}. {place['name']} - {place['address']}, {place['place_id']}")
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+
+    # Example 3: Compute route
+    try:
+        print("\n" + "="*60)
+        print("Example 3: Compute Route")
+        print("="*60)
+
+        places = [
+            {"lat": 25.0408, "lng": 121.5318},  # 台北車站
+            {"lat": 25.0330, "lng": 121.5654},  # 台北101
+            {"lat": 25.0478, "lng": 121.5170},  # 西門町
+        ]
+
+        route = service.compute_routes(
+            place_points=places,
+            start_time=datetime.now(timezone.utc),
+            stop_times=[30],  # 停留時間 (分鐘)
+            travel_mode="DRIVE",
+            routing_preference="TRAFFIC_AWARE" ##"TRAFFIC_AWARE_OPTIMAL"
+        )
+
+        print(f"📊 Total distance: {route['total_distance_meters']}m")
+        print(f"⏱️ Total duration: {route['total_duration_seconds']}s")
+        print(f"🏁 End time: {route['end_time']}")
+
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+        raise e
+
+    # Example 4: Distance matrix
+    try:
+        print("\n" + "="*60)
+        print("Example 4: Distance Matrix")
+        print("="*60)
+
+        origins = [
+            {"lat": 25.0408, "lng": 121.5318},
+            {"lat": 25.0330, "lng": 121.5654},
+        ]
+
+        destinations = [
+            {"lat": 25.0478, "lng": 121.5170},
+            {"lat": 25.0360, "lng": 121.5000},
+        ]
+
+        matrices = service.compute_route_matrix(
+            origins=origins,
+            destinations=destinations,
+            travel_mode="WALK"
+        )
+
+        print("Duration matrix (seconds):")
+        print(matrices["duration_matrix"])
+        print("\nDistance matrix (meters):")
+        print(matrices["distance_matrix"])
+
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+
+    print("\n✅ All examples completed!")

src/services/openweather_service.py

@@ -0,0 +1,606 @@
+"""
+OpenWeatherMap API Service - Improved Version
+
+"""
+
+import requests
+from typing import Dict, Any, Optional, List
+from datetime import datetime, timezone, timedelta
+
+from src.infra.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class OpenWeatherMapService:
+    """
+    OpenWeatherMap API Service
+
+    Provides unified interface to:
+    - Current Weather API
+    - 5 Day Forecast API (3-hour step)
+    - Air Pollution API (Current)
+    - Air Pollution Forecast API (Hourly)
+
+    Free tier limits:
+    - 1,000 calls/day
+    - 60 calls/minute
+    """
+
+    def __init__(self, api_key: Optional[str] = None):
+        """
+        Initialize OpenWeatherMap service
+
+        Args:
+            api_key: OpenWeatherMap API key
+
+        Raises:
+            ValueError: If API key is not provided
+        """
+        # ✅ 改進: 簡化 API key 獲取
+        if api_key:
+            self.api_key = api_key
+        else:
+            import os
+            self.api_key = os.getenv("OPENWEATHER_API_KEY")
+
+            # 如果環境變量沒有，嘗試從配置讀取
+            if not self.api_key:
+                try:
+                    from src.infra.config import get_settings
+                    settings = get_settings()
+                    self.api_key = settings.openweather_api_key
+                except (ImportError, AttributeError):
+                    pass
+
+        # ✅ 改進: 在 __init__ 時就檢查，後面不用重複檢查
+        if not self.api_key:
+            raise ValueError(
+                "OpenWeatherMap API key is required. "  # ✅ 修復錯誤訊息
+                "Set via parameter, config, or OPENWEATHER_API_KEY env var"
+            )
+
+        # API endpoints
+        self.current_weather_url = "https://api.openweathermap.org/data/2.5/weather"
+        self.forecast_weather_url = "https://api.openweathermap.org/data/2.5/forecast"
+        self.air_pollution_url = "https://api.openweathermap.org/data/2.5/air_pollution"
+        self.forecast_air_pollution_url = "https://api.openweathermap.org/data/2.5/air_pollution/forecast"
+
+        logger.info("✅ OpenWeatherMap service initialized")
+
+    # ========================================================================
+    # Helper Functions
+    # ========================================================================
+
+    @staticmethod
+    def _compute_future_index(
+        future_minutes: int,
+        time_step_hours: int = 3
+    ) -> int:
+        """
+        Compute the index in forecast array for a future time
+
+        Args:
+            future_minutes: Minutes into the future
+            time_step_hours: Time step in hours (3 for weather, 1 for air pollution)
+
+        Returns:
+            Index in forecast array
+        """
+        future_hours = future_minutes / 60.0
+        index = int(future_hours / time_step_hours)
+        return index
+
+    @staticmethod
+    def _find_closest_forecast(
+        forecast_list: List[Dict],
+        target_time: datetime
+    ) -> Optional[Dict]:
+        """
+        Find the forecast entry closest to target time
+
+        Args:
+            forecast_list: List of forecast entries with 'timestamp' key
+            target_time: Target datetime
+
+        Returns:
+            Closest forecast entry or None
+        """
+        if not forecast_list:
+            return None
+
+        closest = min(
+            forecast_list,
+            key=lambda x: abs((x['timestamp'] - target_time).total_seconds())
+        )
+        return closest
+
+    # ========================================================================
+    # Current Weather API
+    # ========================================================================
+
+    def get_current_weather(
+        self,
+        location: Dict[str, float],
+        units: str = "metric",
+        lang: str = "zh_tw"
+    ) -> Dict[str, Any]:
+        """
+        Get current weather at location
+
+        Args:
+            location: Location dict with 'lat' and 'lng' keys
+            units: Units (metric/imperial/standard)
+            lang: Language code (zh_tw, en, etc.)
+
+        Returns:
+            Weather data dict with keys:
+                - condition: str (e.g., "Clear", "Rain")
+                - description: str (e.g., "clear sky")
+                - temperature: float (°C if metric)
+                - feels_like: float
+                - temp_min: float
+                - temp_max: float
+                - pressure: int (hPa)
+                - humidity: int (%)
+                - wind_speed: float (m/s if metric)
+                - wind_direction: int (degrees)
+                - cloudiness: int (%)
+                - rain_1h: float (mm)
+                - timestamp: datetime
+
+        Raises:
+            requests.RequestException: If API request fails
+
+        Reference:
+            https://openweathermap.org/current
+        """
+        try:
+            params = {
+                "lat": location["lat"],
+                "lon": location["lng"],
+                "appid": self.api_key,
+                "units": units,
+                "lang": lang
+            }
+
+            logger.debug(
+                f"🌤️ Getting current weather for "
+                f"({location['lat']:.4f}, {location['lng']:.4f})"
+            )
+
+            response = requests.get(
+                self.current_weather_url,
+                params=params,
+                timeout=10
+            )
+
+            response.raise_for_status()
+            data = response.json()
+
+            # ✅ 檢查錯誤
+            if "cod" in data and data["cod"] != 200:
+                raise ValueError(f"API Error: {data.get('message', 'Unknown error')}")
+
+            # Parse response
+            weather = self._parse_current_weather(data)
+
+            logger.info(
+                f"✅ Current weather: {weather['condition']}, "
+                f"{weather['temperature']}°C"
+            )
+
+            return weather
+
+        except requests.Timeout:
+            logger.error("⏰ Weather API request timeout")
+            raise
+        except requests.RequestException as e:
+            logger.error(f"❌ Weather API request error: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"❌ Error getting current weather: {e}")
+            raise
+
+    @staticmethod
+    def _parse_current_weather(data: Dict[str, Any]) -> Dict[str, Any]:
+        """Parse current weather API response"""
+        weather_list = data.get("weather", [])
+        main_weather = weather_list[0] if weather_list else {}
+
+        main_data = data.get("main", {})
+        wind_data = data.get("wind", {})
+        clouds_data = data.get("clouds", {})
+        rain_data = data.get("rain", {})
+
+        return {
+            "condition": main_weather.get("main", "Unknown"),
+            "description": main_weather.get("description", ""),
+            "temperature": main_data.get("temp", 0),
+            "feels_like": main_data.get("feels_like", 0),
+            "temp_min": main_data.get("temp_min", 0),
+            "temp_max": main_data.get("temp_max", 0),
+            "pressure": main_data.get("pressure", 0),
+            "humidity": main_data.get("humidity", 0),
+            "wind_speed": wind_data.get("speed", 0),
+            "wind_direction": wind_data.get("deg", 0),
+            "cloudiness": clouds_data.get("all", 0),
+            "rain_1h": rain_data.get("1h", 0),
+            "timestamp": datetime.fromtimestamp(
+                data.get("dt", 0),
+                tz=timezone.utc
+            )
+        }
+
+    # ========================================================================
+    # 5 Day Forecast API (3-hour step)
+    # ========================================================================
+    @staticmethod
+    def _parse_forecast_weather(data: Dict[str, Any]) -> Dict[str, Any]:
+        """Parse 5-day forecast API response"""
+        forecast_list = data.get("list", [])
+
+        hourly = []
+        for item in forecast_list:
+            weather_list = item.get("weather", [])
+            main_weather = weather_list[0] if weather_list else {}
+
+            main_data = item.get("main", {})
+            wind_data = item.get("wind", {})
+            rain_data = item.get("rain", {})
+
+            hourly.append({
+                "timestamp": datetime.fromtimestamp(
+                    item.get("dt", 0),
+                    tz=timezone.utc
+                ),
+                "condition": main_weather.get("main", "Unknown"),
+                "description": main_weather.get("description", ""),
+                "temperature": main_data.get("temp", 0),
+                "feels_like": main_data.get("feels_like", 0),
+                "humidity": main_data.get("humidity", 0),
+                "wind_speed": wind_data.get("speed", 0),
+                "rain_3h": rain_data.get("3h", 0),
+                "pop": item.get("pop", 0)  # Probability of precipitation
+            })
+
+        return {
+            "hourly": hourly,
+            "city": data.get("city", {})
+        }
+
+    # ========================================================================
+    # Current Air Pollution API
+    # ========================================================================
+
+    def get_air_pollution(
+        self,
+        location: Dict[str, float]
+    ) -> Dict[str, Any]:
+        """
+        Get current air pollution data
+
+        Args:
+            location: Location dict with 'lat' and 'lng' keys
+
+        Returns:
+            Air quality dict with keys:
+                - aqi: int (1-5, 1=Good, 5=Very Poor)
+                - aqi_label: str ("Good", "Fair", etc.)
+                - co: float (Carbon monoxide, μg/m³)
+                - no: float (Nitrogen monoxide, μg/m³)
+                - no2: float (Nitrogen dioxide, μg/m³)
+                - o3: float (Ozone, μg/m³)
+                - so2: float (Sulphur dioxide, μg/m³)
+                - pm2_5: float (Fine particles, μg/m³)
+                - pm10: float (Coarse particles, μg/m³)
+                - nh3: float (Ammonia, μg/m³)
+                - timestamp: datetime
+
+        Raises:
+            requests.RequestException: If API request fails
+
+        Reference:
+            https://openweathermap.org/api/air-pollution
+        """
+        try:
+            params = {
+                "lat": location["lat"],
+                "lon": location["lng"],
+                "appid": self.api_key
+            }
+
+            logger.debug(
+                f"🌫️ Getting air pollution for "
+                f"({location['lat']:.4f}, {location['lng']:.4f})"
+            )
+
+            response = requests.get(
+                self.air_pollution_url,
+                params=params,
+                timeout=10
+            )
+
+            response.raise_for_status()
+            data = response.json()
+
+            # Parse response
+            pollution = self._parse_air_pollution(data)
+
+            logger.info(
+                f"✅ Air quality: AQI {pollution['aqi']} ({pollution['aqi_label']})"
+            )
+
+            return pollution
+
+        except requests.Timeout:
+            logger.error("⏰ Air Pollution API request timeout")
+            raise
+        except requests.RequestException as e:
+            logger.error(f"❌ Air Pollution API request error: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"❌ Error getting air pollution: {e}")
+            raise
+
+    def _parse_air_pollution(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Parse air pollution API response"""
+        list_data = data.get("list", [])
+        if not list_data:
+            return {
+                "aqi": 0,
+                "aqi_label": "Unknown",
+                "co": 0,
+                "no": 0,
+                "no2": 0,
+                "o3": 0,
+                "so2": 0,
+                "pm2_5": 0,
+                "pm10": 0,
+                "nh3": 0,
+                "timestamp": datetime.now(timezone.utc)
+            }
+
+        item = list_data[0]
+        main = item.get("main", {})
+        components = item.get("components", {})
+
+        # AQI levels: 1 = Good, 2 = Fair, 3 = Moderate, 4 = Poor, 5 = Very Poor
+        aqi = main.get("aqi", 0)
+        aqi_labels = {
+            1: "Good",
+            2: "Fair",
+            3: "Moderate",
+            4: "Poor",
+            5: "Very Poor"
+        }
+
+        return {
+            "aqi": aqi,
+            "aqi_label": aqi_labels.get(aqi, "Unknown"),
+            "co": components.get("co", 0),
+            "no": components.get("no", 0),
+            "no2": components.get("no2", 0),
+            "o3": components.get("o3", 0),
+            "so2": components.get("so2", 0),
+            "pm2_5": components.get("pm2_5", 0),
+            "pm10": components.get("pm10", 0),
+            "nh3": components.get("nh3", 0),
+            "timestamp": datetime.fromtimestamp(
+                item.get("dt", 0),
+                tz=timezone.utc
+            )
+        }
+
+    # ========================================================================
+    # ✅ 新增: Air Pollution Forecast API (Hourly)
+    # ========================================================================
+
+    def get_forecast_weather(
+        self,
+        location: Dict[str, float],
+        future_minutes: int = 0,
+    ) -> Dict[str, Any]:
+        """
+        Get weather forecast for a specific time in the future.
+        Use this to check conditions for planned activities (e.g., "Will it rain at 3 PM?").
+
+        Args:
+            location: Target location {"lat": float, "lng": float}.
+            future_minutes: Minutes from NOW. (e.g., 0=now, 180=in 3 hours).
+
+        Returns:
+            Dict: Forecast data including:
+            - timestamp: datetime
+            - condition: str
+            - temperature: float
+            - pop: float (Probability of Precipitation 0-1)
+        """
+        try:
+            params = {
+                "lat": location["lat"],
+                "lon": location["lng"],
+                "appid": self.api_key,
+                "units": "metric",
+                "lang": "zh_tw"
+            }
+
+            response = requests.get(self.forecast_weather_url, params=params, timeout=10)
+            response.raise_for_status()
+            data = response.json()
+
+            if "cod" in data and data["cod"] != "200":
+                raise ValueError(f"API Error: {data.get('message', 'Unknown error')}")
+
+            forecast = self._parse_forecast_weather(data)
+
+            if future_minutes == 0:
+                return forecast['hourly'][0] if forecast['hourly'] else {}
+            else:
+                target_time = datetime.now(timezone.utc) + timedelta(minutes=future_minutes)
+                closest = self._find_closest_forecast(forecast['hourly'], target_time)
+                return closest if closest else {}
+
+        except Exception as e:
+            logger.error(f"❌ Error getting forecast: {e}")
+            raise
+
+    @staticmethod
+    def _parse_forecast_air_pollution(data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        ✅ 新增方法: Parse air pollution forecast API response
+        """
+        list_data = data.get("list", [])
+
+        hourly = []
+        aqi_labels = {
+            1: "Good",
+            2: "Fair",
+            3: "Moderate",
+            4: "Poor",
+            5: "Very Poor"
+        }
+
+        for item in list_data:
+            main = item.get("main", {})
+            components = item.get("components", {})
+            aqi = main.get("aqi", 0)
+
+            hourly.append({
+                "timestamp": datetime.fromtimestamp(
+                    item.get("dt", 0),
+                    tz=timezone.utc
+                ),
+                "aqi": aqi,
+                "aqi_label": aqi_labels.get(aqi, "Unknown"),
+                "co": components.get("co", 0),
+                "no": components.get("no", 0),
+                "no2": components.get("no2", 0),
+                "o3": components.get("o3", 0),
+                "so2": components.get("so2", 0),
+                "pm2_5": components.get("pm2_5", 0),
+                "pm10": components.get("pm10", 0),
+                "nh3": components.get("nh3", 0),
+            })
+
+        return {
+            "hourly": hourly
+        }
+
+    def get_forecast_air_pollution(
+            self,
+            location: Dict[str, float],
+            future_minutes: int = 0
+    ) -> Dict[str, Any]:
+        """
+        Get air quality (AQI) forecast for a future time.
+
+        Args:
+            location: Target location {"lat": float, "lng": float}.
+            future_minutes: Minutes from NOW.
+
+        Returns:
+            Dict: Air quality data including:
+            - aqi: int (1=Good, 5=Very Poor)
+            - pm2_5: float
+            - timestamp: datetime
+        """
+        try:
+            params = {
+                "lat": location["lat"],
+                "lon": location["lng"],
+                "appid": self.api_key
+            }
+
+            response = requests.get(self.forecast_air_pollution_url, params=params, timeout=10)
+            response.raise_for_status()
+            data = response.json()
+
+            forecast = self._parse_forecast_air_pollution(data)
+
+            if future_minutes == 0:
+                return forecast['hourly'][0] if forecast['hourly'] else {}
+            else:
+                target_time = datetime.now(timezone.utc) + timedelta(minutes=future_minutes)
+                closest = self._find_closest_forecast(forecast['hourly'], target_time)
+                return closest if closest else {}
+
+        except Exception as e:
+            logger.error(f"❌ Error getting air pollution forecast: {e}")
+            raise
+
+
+# ============================================================================
+# Usage Examples
+# ============================================================================
+
+if __name__ == "__main__":
+    import os
+    from src.infra.config import get_settings
+    settings = get_settings()
+
+    # Initialize service
+    api_key = settings.openweather_api_key
+    if not api_key:
+        print("❌ Please set OPENWEATHER_API_KEY environment variable")
+        print("   Get your free API key at: https://openweathermap.org/api")
+        exit(1)
+
+    service = OpenWeatherMapService(api_key=api_key)
+
+    # Test location (Taipei 101)
+    taipei_101 = {"lat": 25.0330, "lng": 121.5654}
+
+    # Example 1: Current weather
+    try:
+        print("\n" + "="*60)
+        print("Example 1: Current Weather")
+        print("="*60)
+        weather = service.get_current_weather(taipei_101)
+        print(f"🌡️ Temperature: {weather['temperature']}°C")
+        print(f"💧 Humidity: {weather['humidity']}%")
+        print(f"🌤️ Condition: {weather['condition']} ({weather['description']})")
+        print(f"💨 Wind: {weather['wind_speed']} m/s")
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+
+    # Example 2: Weather forecast (3 hours from now)
+    try:
+        print("\n" + "="*60)
+        print("Example 2: Weather Forecast (3 hours)")
+        print("="*60)
+        forecast = service.get_forecast_weather(taipei_101, future_minutes=180)
+        print(f"⏰ Time: {forecast['timestamp']}")
+        print(f"🌡️ Temperature: {forecast['temperature']}°C")
+        print(f"🌧️ Precipitation probability: {forecast['pop']*100:.0f}%")
+        print(f"🌤️ Condition: {forecast['condition']}")
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+
+    # Example 3: Current air quality
+    try:
+        print("\n" + "="*60)
+        print("Example 3: Current Air Quality")
+        print("="*60)
+        air = service.get_air_pollution(taipei_101)
+        print(f"🌫️ AQI: {air['aqi']} ({air['aqi_label']})")
+        print(f"   PM2.5: {air['pm2_5']:.1f} μg/m³")
+        print(f"   PM10: {air['pm10']:.1f} μg/m³")
+        print(f"   O3: {air['o3']:.1f} μg/m³")
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+
+    # Example 4: Air quality forecast (6 hours from now)
+    try:
+        print("\n" + "="*60)
+        print("Example 4: Air Quality Forecast (6 hours)")
+        print("="*60)
+        forecast_air = service.get_forecast_air_pollution(taipei_101, future_minutes=360)
+        print(f"⏰ Time: {forecast_air['timestamp']}")
+        print(f"🌫️ AQI: {forecast_air['aqi']} ({forecast_air['aqi_label']})")
+        print(f"   PM2.5: {forecast_air['pm2_5']:.1f} μg/m³")
+        print(f"   PM10: {forecast_air['pm10']:.1f} μg/m³")
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+
+    print("\n✅ All examples completed!")