feat: google apis added

.gitignore

@@ -136,4 +136,5 @@ deploy_hf.py
 
 ddl
 API_DESCRIPTION.md
-ENTERPRISE-API-ROADMAP*.md
+ENTERPRISE-API-ROADMAP*.md
+API-Implementation-Plan

app/api/v1/google_maps.py

@@ -0,0 +1,668 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+from fastapi import APIRouter, Depends, Header, Query, Response
+
+from app.api.deps import require_auth
+from app.core.logger import get_logger
+from app.models.schemas import (
+    GoogleAutocompleteMatchedSubstring,
+    GoogleAutocompletePrediction,
+    GoogleAutocompleteStructuredFormatting,
+    GoogleAutocompleteTerm,
+    GoogleGeocodeRequest,
+    GoogleGeocodeResponse,
+    GoogleGeocodeResult,
+    GooglePlaceAutocompleteRequest,
+    GooglePlaceAutocompleteResponse,
+    GooglePlaceDetailsRequest,
+    GooglePlaceDetailsResponse,
+    GooglePlacePhoto,
+    GooglePlaceResult,
+    GooglePlacesNearbyRequest,
+    GooglePlacesNearbyResponse,
+    GooglePlacesSearchRequest,
+    GooglePlacesSearchResponse,
+    GoogleQueryAutocompleteRequest,
+    GoogleQueryAutocompleteResponse,
+    GoogleReverseGeocodeRequest,
+)
+from app.services.google_maps_service import GoogleMapsService, PRICE_LEVEL_MAP
+
+router = APIRouter(prefix="/google", tags=["Google Maps"])
+_logger = get_logger(__name__)
+
+
+def get_maps_service() -> GoogleMapsService:
+    return GoogleMapsService()
+
+
+# ---------------------------------------------------------------------------
+# Legacy response builders (for Geocoding — still on Google Geocoding API)
+# ---------------------------------------------------------------------------
+
+def _build_geocode_results(data: dict) -> list[GoogleGeocodeResult]:
+    results: list[GoogleGeocodeResult] = []
+    for r in data.get("results", []):
+        geometry = r.get("geometry", {})
+        location = geometry.get("location", {})
+        results.append(GoogleGeocodeResult(
+            formatted_address=r.get("formatted_address", ""),
+            place_id=r.get("place_id", ""),
+            latitude=location.get("lat", 0.0),
+            longitude=location.get("lng", 0.0),
+            location_type=geometry.get("location_type", ""),
+            address_components=r.get("address_components", []),
+            types=r.get("types", []),
+        ))
+    return results
+
+
+# ---------------------------------------------------------------------------
+# New Places API response builders
+# ---------------------------------------------------------------------------
+
+def _parse_photos(photos_raw: list[dict]) -> list[GooglePlacePhoto]:
+    photos: list[GooglePlacePhoto] = []
+    for p in photos_raw:
+        photos.append(GooglePlacePhoto(
+            photo_reference=p.get("name", ""),
+            height=p.get("heightPx", 0),
+            width=p.get("widthPx", 0),
+            html_attributions=[
+                a.get("displayName", "") for a in p.get("authorAttributions", [])
+            ],
+        ))
+    return photos
+
+
+def _build_place_results_new(data: dict) -> list[GooglePlaceResult]:
+    results: list[GooglePlaceResult] = []
+    for p in data.get("places", []):
+        loc = p.get("location", {})
+        price_level_str = p.get("priceLevel", "")
+        results.append(GooglePlaceResult(
+            place_id=p.get("id", ""),
+            name=p.get("displayName", {}).get("text", ""),
+            formatted_address=p.get("formattedAddress", ""),
+            latitude=loc.get("latitude", 0.0),
+            longitude=loc.get("longitude", 0.0),
+            rating=p.get("rating"),
+            user_ratings_total=p.get("userRatingCount"),
+            price_level=PRICE_LEVEL_MAP.get(price_level_str) if price_level_str else None,
+            types=p.get("types", []),
+            vicinity=p.get("shortFormattedAddress", ""),
+            business_status=p.get("businessStatus", ""),
+            photos=_parse_photos(p.get("photos", [])),
+            plus_code=p.get("plusCode", {}).get("globalCode") if p.get("plusCode") else None,
+            icon=p.get("iconMaskBaseUri"),
+            opening_hours=p.get("regularOpeningHours") or p.get("currentOpeningHours"),
+            website=p.get("websiteUri"),
+            formatted_phone_number=p.get("nationalPhoneNumber"),
+            international_phone_number=p.get("internationalPhoneNumber"),
+            google_maps_uri=p.get("googleMapsUri"),
+        ))
+    return results
+
+
+def _build_place_detail_new(data: dict) -> Optional[GooglePlaceResult]:
+    if not data or not data.get("id"):
+        return None
+    loc = data.get("location", {})
+    price_level_str = data.get("priceLevel", "")
+    return GooglePlaceResult(
+        place_id=data.get("id", ""),
+        name=data.get("displayName", {}).get("text", ""),
+        formatted_address=data.get("formattedAddress", ""),
+        latitude=loc.get("latitude", 0.0),
+        longitude=loc.get("longitude", 0.0),
+        rating=data.get("rating"),
+        user_ratings_total=data.get("userRatingCount"),
+        price_level=PRICE_LEVEL_MAP.get(price_level_str) if price_level_str else None,
+        types=data.get("types", []),
+        vicinity=data.get("shortFormattedAddress", ""),
+        business_status=data.get("businessStatus", ""),
+        photos=_parse_photos(data.get("photos", [])),
+        plus_code=data.get("plusCode", {}).get("globalCode") if data.get("plusCode") else None,
+        icon=data.get("iconMaskBaseUri"),
+        opening_hours=data.get("regularOpeningHours") or data.get("currentOpeningHours"),
+        website=data.get("websiteUri"),
+        formatted_phone_number=data.get("nationalPhoneNumber"),
+        international_phone_number=data.get("internationalPhoneNumber"),
+        google_maps_uri=data.get("googleMapsUri"),
+    )
+
+
+def _build_autocomplete_predictions_new(data: dict) -> list[GoogleAutocompletePrediction]:
+    predictions: list[GoogleAutocompletePrediction] = []
+    for s in data.get("suggestions", []):
+        pp = s.get("placePrediction") or s.get("queryPrediction")
+        if not pp:
+            continue
+
+        text = pp.get("text", {})
+        description = text.get("text", "") if isinstance(text, dict) else str(text)
+        place_id = pp.get("placeId", "")
+
+        sf_raw = pp.get("structuredFormat", {}) or pp.get("structuredFormatting", {})
+        sf = None
+        if sf_raw:
+            main_text = sf_raw.get("mainText", {})
+            if isinstance(main_text, dict):
+                main_text = main_text.get("text", "")
+            secondary_text = sf_raw.get("secondaryText", {})
+            if isinstance(secondary_text, dict):
+                secondary_text = secondary_text.get("text", "")
+            main_matches_raw = sf_raw.get("mainTextMatchedSubstrings", [])
+            secondary_matches_raw = sf_raw.get("secondaryTextMatchedSubstrings", [])
+            sf = GoogleAutocompleteStructuredFormatting(
+                main_text=main_text,
+                main_text_matched_substrings=[
+                    GoogleAutocompleteMatchedSubstring(**m) for m in main_matches_raw
+                ],
+                secondary_text=secondary_text,
+                secondary_text_matched_substrings=[
+                    GoogleAutocompleteMatchedSubstring(**m) for m in secondary_matches_raw
+                ],
+            )
+
+        terms = [
+            GoogleAutocompleteTerm(offset=0, value=description)
+        ]
+        types = pp.get("types", [])
+
+        predictions.append(GoogleAutocompletePrediction(
+            description=description,
+            place_id=place_id,
+            structured_formatting=sf,
+            terms=terms,
+            types=types,
+            matched_substrings=[],
+            distance_meters=pp.get("distanceMeters"),
+        ))
+    return predictions
+
+
+def _build_autocomplete_predictions_legacy(data: dict) -> list[GoogleAutocompletePrediction]:
+    predictions: list[GoogleAutocompletePrediction] = []
+    for p in data.get("predictions", []):
+        sf_raw = p.get("structured_formatting")
+        sf = None
+        if sf_raw:
+            main_matches = [
+                GoogleAutocompleteMatchedSubstring(**m)
+                for m in sf_raw.get("main_text_matched_substrings", [])
+            ]
+            secondary_matches = [
+                GoogleAutocompleteMatchedSubstring(**m)
+                for m in sf_raw.get("secondary_text_matched_substrings", [])
+            ]
+            sf = GoogleAutocompleteStructuredFormatting(
+                main_text=sf_raw.get("main_text", ""),
+                main_text_matched_substrings=main_matches,
+                secondary_text=sf_raw.get("secondary_text", ""),
+                secondary_text_matched_substrings=secondary_matches,
+            )
+        terms = [GoogleAutocompleteTerm(**t) for t in p.get("terms", [])]
+        matched_subs = [
+            GoogleAutocompleteMatchedSubstring(**m)
+            for m in p.get("matched_substrings", [])
+        ]
+        predictions.append(GoogleAutocompletePrediction(
+            description=p.get("description", ""),
+            place_id=p.get("place_id", ""),
+            structured_formatting=sf,
+            terms=terms,
+            types=p.get("types", []),
+            matched_substrings=matched_subs,
+            distance_meters=p.get("distance_meters"),
+        ))
+    return predictions
+
+
+# ---------------------------------------------------------------------------
+# Routes — Autocomplete
+# ---------------------------------------------------------------------------
+
+@router.post("/places/autocomplete", response_model=GooglePlaceAutocompleteResponse,
+             summary="Get place predictions for autocomplete input (New Places API)")
+async def place_autocomplete(
+    body: GooglePlaceAutocompleteRequest,
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    start = time.perf_counter()
+    result = await service.place_autocomplete(
+        input=body.input,
+        offset=body.offset,
+        origin=body.origin,
+        location=body.location,
+        radius=body.radius,
+        language=body.language,
+        types=body.types,
+        components=body.components,
+        strictbounds=body.strictbounds,
+        sessiontoken=body.sessiontoken,
+        api_key=x_goog_api_key,
+    )
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+    error = result.get("error")
+    if error:
+        return GooglePlaceAutocompleteResponse(success=False, time_ms=elapsed_ms, predictions=[], count=0, error=error)
+    data = result.get("data", {})
+    predictions = _build_autocomplete_predictions_new(data)
+    return GooglePlaceAutocompleteResponse(success=True, time_ms=elapsed_ms, predictions=predictions, count=len(predictions))
+
+
+@router.get("/places/autocomplete", response_model=GooglePlaceAutocompleteResponse,
+            summary="Get place predictions for autocomplete input (GET, New Places API)")
+async def place_autocomplete_get(
+    input: str = Query(..., min_length=1, max_length=1000, description="Text string to search for"),
+    offset: Optional[int] = Query(None, ge=1),
+    origin: Optional[str] = Query(None, pattern=r"^-?\d+\.?\d*,-?\d+\.?\d*$"),
+    location: Optional[str] = Query(None, pattern=r"^-?\d+\.?\d*,-?\d+\.?\d*$"),
+    radius: Optional[int] = Query(None, ge=1, le=50000),
+    language: Optional[str] = Query(None, max_length=10),
+    types: Optional[str] = Query(None),
+    components: Optional[str] = Query(None),
+    strictbounds: Optional[bool] = Query(None),
+    sessiontoken: Optional[str] = Query(None),
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    start = time.perf_counter()
+    result = await service.place_autocomplete(
+        input=input, offset=offset, origin=origin, location=location,
+        radius=radius, language=language, types=types, components=components,
+        strictbounds=strictbounds, sessiontoken=sessiontoken,
+        api_key=x_goog_api_key,
+    )
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+    error = result.get("error")
+    if error:
+        return GooglePlaceAutocompleteResponse(success=False, time_ms=elapsed_ms, predictions=[], count=0, error=error)
+    data = result.get("data", {})
+    predictions = _build_autocomplete_predictions_new(data)
+    return GooglePlaceAutocompleteResponse(success=True, time_ms=elapsed_ms, predictions=predictions, count=len(predictions))
+
+
+@router.post("/places/queryautocomplete", response_model=GoogleQueryAutocompleteResponse,
+             summary="Get query predictions for autocomplete input (New Places API)")
+async def query_autocomplete(
+    body: GoogleQueryAutocompleteRequest,
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    start = time.perf_counter()
+    result = await service.query_autocomplete(
+        input=body.input,
+        offset=body.offset,
+        location=body.location,
+        radius=body.radius,
+        language=body.language,
+        api_key=x_goog_api_key,
+    )
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+    error = result.get("error")
+    if error:
+        return GoogleQueryAutocompleteResponse(success=False, time_ms=elapsed_ms, predictions=[], count=0, error=error)
+    data = result.get("data", {})
+    predictions = _build_autocomplete_predictions_new(data)
+    return GoogleQueryAutocompleteResponse(success=True, time_ms=elapsed_ms, predictions=predictions, count=len(predictions))
+
+
+@router.get("/places/queryautocomplete", response_model=GoogleQueryAutocompleteResponse,
+            summary="Get query predictions for autocomplete input (GET, New Places API)")
+async def query_autocomplete_get(
+    input: str = Query(..., min_length=1, max_length=1000, description="Text string to search for"),
+    offset: Optional[int] = Query(None, ge=1),
+    location: Optional[str] = Query(None, pattern=r"^-?\d+\.?\d*,-?\d+\.?\d*$"),
+    radius: Optional[int] = Query(None, ge=1, le=50000),
+    language: Optional[str] = Query(None, max_length=10),
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    start = time.perf_counter()
+    result = await service.query_autocomplete(
+        input=input, offset=offset, location=location,
+        radius=radius, language=language,
+        api_key=x_goog_api_key,
+    )
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+    error = result.get("error")
+    if error:
+        return GoogleQueryAutocompleteResponse(success=False, time_ms=elapsed_ms, predictions=[], count=0, error=error)
+    data = result.get("data", {})
+    predictions = _build_autocomplete_predictions_new(data)
+    return GoogleQueryAutocompleteResponse(success=True, time_ms=elapsed_ms, predictions=predictions, count=len(predictions))
+
+
+# ---------------------------------------------------------------------------
+# Routes — Geocoding (still uses legacy API)
+# ---------------------------------------------------------------------------
+
+@router.post("/geocode", response_model=GoogleGeocodeResponse, summary="Forward geocode an address")
+async def geocode(
+    body: GoogleGeocodeRequest,
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    start = time.perf_counter()
+    result = await service.geocode(
+        address=body.address,
+        region=body.region,
+        language=body.language,
+        bounds=body.bounds,
+        api_key=x_goog_api_key,
+    )
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+    error = result.get("error")
+    if error:
+        return GoogleGeocodeResponse(success=False, time_ms=elapsed_ms, results=[], count=0, error=error)
+    data = result.get("data", {})
+    results = _build_geocode_results(data)
+    return GoogleGeocodeResponse(success=True, time_ms=elapsed_ms, results=results, count=len(results))
+
+
+@router.get("/geocode", response_model=GoogleGeocodeResponse, summary="Forward geocode an address (GET)")
+async def geocode_get(
+    address: str = Query(..., min_length=1, max_length=1000, description="Street address to geocode"),
+    region: Optional[str] = Query(None, max_length=2),
+    language: Optional[str] = Query(None, max_length=10),
+    bounds: Optional[str] = Query(None),
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    start = time.perf_counter()
+    result = await service.geocode(address=address, region=region, language=language, bounds=bounds, api_key=x_goog_api_key)
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+    error = result.get("error")
+    if error:
+        return GoogleGeocodeResponse(success=False, time_ms=elapsed_ms, results=[], count=0, error=error)
+    data = result.get("data", {})
+    results = _build_geocode_results(data)
+    return GoogleGeocodeResponse(success=True, time_ms=elapsed_ms, results=results, count=len(results))
+
+
+@router.post("/reverse-geocode", response_model=GoogleGeocodeResponse, summary="Reverse geocode coordinates to an address")
+async def reverse_geocode(
+    body: GoogleReverseGeocodeRequest,
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    start = time.perf_counter()
+    result = await service.reverse_geocode(
+        latlng=body.latlng,
+        language=body.language,
+        result_type=body.result_type,
+        location_type=body.location_type,
+        api_key=x_goog_api_key,
+    )
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+    error = result.get("error")
+    if error:
+        return GoogleGeocodeResponse(success=False, time_ms=elapsed_ms, results=[], count=0, error=error)
+    data = result.get("data", {})
+    results = _build_geocode_results(data)
+    return GoogleGeocodeResponse(success=True, time_ms=elapsed_ms, results=results, count=len(results))
+
+
+@router.get("/reverse-geocode", response_model=GoogleGeocodeResponse, summary="Reverse geocode coordinates to an address (GET)")
+async def reverse_geocode_get(
+    latlng: str = Query(..., pattern=r"^-?\d+\.?\d*,-?\d+\.?\d*$", description="Latitude,Longitude"),
+    language: Optional[str] = Query(None, max_length=10),
+    result_type: Optional[str] = Query(None),
+    location_type: Optional[str] = Query(None),
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    start = time.perf_counter()
+    result = await service.reverse_geocode(
+        latlng=latlng, language=language,
+        result_type=result_type, location_type=location_type,
+        api_key=x_goog_api_key,
+    )
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+    error = result.get("error")
+    if error:
+        return GoogleGeocodeResponse(success=False, time_ms=elapsed_ms, results=[], count=0, error=error)
+    data = result.get("data", {})
+    results = _build_geocode_results(data)
+    return GoogleGeocodeResponse(success=True, time_ms=elapsed_ms, results=results, count=len(results))
+
+
+# ---------------------------------------------------------------------------
+# Routes — Places Search / Nearby / Details (New Places API)
+# ---------------------------------------------------------------------------
+
+@router.post("/places/search", response_model=GooglePlacesSearchResponse, summary="Search for places using a text query (New Places API)")
+async def places_search(
+    body: GooglePlacesSearchRequest,
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    start = time.perf_counter()
+    result = await service.places_search(
+        query=body.query,
+        region=body.region,
+        language=body.language,
+        min_price=body.min_price,
+        max_price=body.max_price,
+        open_now=body.open_now,
+        type_filter=body.type,
+        radius=body.radius,
+        page_token=body.page_token,
+        page_size=body.page_size,
+        min_rating=body.min_rating,
+        api_key=x_goog_api_key,
+    )
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+    error = result.get("error")
+    if error:
+        return GooglePlacesSearchResponse(success=False, time_ms=elapsed_ms, results=[], count=0, error=error)
+    data = result.get("data", {})
+    results = _build_place_results_new(data)
+    return GooglePlacesSearchResponse(
+        success=True, time_ms=elapsed_ms, results=results,
+        count=len(results), next_page_token=data.get("nextPageToken"),
+    )
+
+
+@router.post("/places/nearby", response_model=GooglePlacesNearbyResponse, summary="Search for places near a location (New Places API)")
+async def places_nearby(
+    body: GooglePlacesNearbyRequest,
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    start = time.perf_counter()
+    result = await service.places_nearby(
+        location=body.location,
+        radius=body.radius,
+        keyword=body.keyword,
+        language=body.language,
+        min_price=body.min_price,
+        max_price=body.max_price,
+        open_now=body.open_now,
+        type_filter=body.type,
+        page_token=body.page_token,
+        page_size=body.page_size,
+        rank_preference=body.rank_preference,
+        api_key=x_goog_api_key,
+    )
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+    error = result.get("error")
+    if error:
+        return GooglePlacesNearbyResponse(success=False, time_ms=elapsed_ms, results=[], count=0, error=error)
+    data = result.get("data", {})
+    results = _build_place_results_new(data)
+    return GooglePlacesNearbyResponse(
+        success=True, time_ms=elapsed_ms, results=results,
+        count=len(results), next_page_token=data.get("nextPageToken"),
+    )
+
+
+@router.get("/places/search", response_model=GooglePlacesSearchResponse,
+            summary="Search for places using a text query (GET, New Places API)")
+async def places_search_get(
+    query: str = Query(..., min_length=1, max_length=1000, description="Text query for place search"),
+    region: Optional[str] = Query(None, max_length=2),
+    language: Optional[str] = Query(None, max_length=10),
+    type_filter: Optional[str] = Query(None, alias="type"),
+    radius: Optional[int] = Query(None, ge=1, le=50000),
+    min_price: Optional[int] = Query(None, ge=0, le=4, description="Minimum price level (0=free, 4=most expensive)"),
+    max_price: Optional[int] = Query(None, ge=0, le=4, description="Maximum price level (0=free, 4=most expensive)"),
+    open_now: Optional[bool] = Query(None, description="Only return places that are open now"),
+    page_token: Optional[str] = Query(None, description="Token for pagination"),
+    page_size: Optional[int] = Query(None, ge=1, le=200, description="Number of results per page"),
+    min_rating: Optional[float] = Query(None, ge=0.0, le=5.0, description="Minimum rating filter"),
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    start = time.perf_counter()
+    result = await service.places_search(
+        query=query, region=region, language=language, type_filter=type_filter,
+        radius=radius, min_price=min_price, max_price=max_price, open_now=open_now,
+        page_token=page_token, page_size=page_size, min_rating=min_rating,
+        api_key=x_goog_api_key,
+    )
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+    error = result.get("error")
+    if error:
+        return GooglePlacesSearchResponse(success=False, time_ms=elapsed_ms, results=[], count=0, error=error)
+    data = result.get("data", {})
+    results = _build_place_results_new(data)
+    return GooglePlacesSearchResponse(
+        success=True, time_ms=elapsed_ms, results=results,
+        count=len(results), next_page_token=data.get("nextPageToken"),
+    )
+
+
+@router.get("/places/nearby", response_model=GooglePlacesNearbyResponse,
+            summary="Search for places near a location (GET, New Places API)")
+async def places_nearby_get(
+    location: str = Query(..., pattern=r"^-?\d+\.?\d*,-?\d+\.?\d*$", description="Latitude,Longitude"),
+    radius: int = Query(1000, ge=1, le=50000),
+    keyword: Optional[str] = Query(None, max_length=500),
+    language: Optional[str] = Query(None, max_length=10),
+    type_filter: Optional[str] = Query(None, alias="type"),
+    min_price: Optional[int] = Query(None, ge=0, le=4, description="Minimum price level"),
+    max_price: Optional[int] = Query(None, ge=0, le=4, description="Maximum price level"),
+    open_now: Optional[bool] = Query(None, description="Only return places that are open now"),
+    page_token: Optional[str] = Query(None, description="Token for pagination"),
+    page_size: Optional[int] = Query(None, ge=1, le=200, description="Number of results per page"),
+    rank_preference: Optional[str] = Query(None, pattern="^(POPULARITY|DISTANCE)$", description="Ranking preference"),
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    start = time.perf_counter()
+    result = await service.places_nearby(
+        location=location, radius=radius, keyword=keyword,
+        language=language, type_filter=type_filter,
+        min_price=min_price, max_price=max_price, open_now=open_now,
+        page_token=page_token, page_size=page_size, rank_preference=rank_preference,
+        api_key=x_goog_api_key,
+    )
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+    error = result.get("error")
+    if error:
+        return GooglePlacesNearbyResponse(success=False, time_ms=elapsed_ms, results=[], count=0, error=error)
+    data = result.get("data", {})
+    results = _build_place_results_new(data)
+    return GooglePlacesNearbyResponse(
+        success=True, time_ms=elapsed_ms, results=results,
+        count=len(results), next_page_token=data.get("nextPageToken"),
+    )
+
+
+@router.post("/places/details", response_model=GooglePlaceDetailsResponse,
+             summary="Get detailed information about a place (New Places API)")
+async def place_details(
+    body: GooglePlaceDetailsRequest,
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    start = time.perf_counter()
+    result = await service.place_details(
+        place_id=body.place_id,
+        region=body.region,
+        language=body.language,
+        fields=body.fields,
+        api_key=x_goog_api_key,
+    )
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+    error = result.get("error")
+    if error:
+        return GooglePlaceDetailsResponse(success=False, time_ms=elapsed_ms, result=None, error=error)
+    data = result.get("data", {})
+    detail = _build_place_detail_new(data)
+    return GooglePlaceDetailsResponse(success=True, time_ms=elapsed_ms, result=detail)
+
+
+@router.get("/places/details", response_model=GooglePlaceDetailsResponse,
+            summary="Get detailed information about a place (GET, New Places API)")
+async def place_details_get(
+    place_id: str = Query(..., min_length=1, max_length=500, description="Google Place ID"),
+    region: Optional[str] = Query(None, max_length=2),
+    language: Optional[str] = Query(None, max_length=10),
+    fields: Optional[str] = Query(None),
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    start = time.perf_counter()
+    result = await service.place_details(
+        place_id=place_id, region=region, language=language, fields=fields,
+        api_key=x_goog_api_key,
+    )
+    elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+    error = result.get("error")
+    if error:
+        return GooglePlaceDetailsResponse(success=False, time_ms=elapsed_ms, result=None, error=error)
+    data = result.get("data", {})
+    detail = _build_place_detail_new(data)
+    return GooglePlaceDetailsResponse(success=True, time_ms=elapsed_ms, result=detail)
+
+
+@router.get("/places/photo",
+            summary="Get a place photo by photo reference (New Places API)")
+async def place_photo(
+    photo_reference: str = Query(..., min_length=1, description="Photo reference name (e.g. 'places/ChIJ.../photos/...')"),
+    max_width_px: int = Query(400, ge=1, le=4800),
+    max_height_px: int = Query(400, ge=1, le=4800),
+    x_goog_api_key: str = Header(..., alias="X-Goog-Api-Key", description="Your Google API key"),
+    token: str = Depends(require_auth),
+    service: GoogleMapsService = Depends(get_maps_service),
+):
+    from app.config import get_settings
+    import httpx
+
+    cfg = get_settings()
+    url = f"{cfg.google_maps_places_base_url}/{photo_reference}/media"
+    headers = {"X-Goog-Api-Key": x_goog_api_key}
+    params = {"maxWidthPx": max_width_px, "maxHeightPx": max_height_px}
+
+    async with httpx.AsyncClient(timeout=cfg.google_maps_timeout, follow_redirects=True) as client:
+        resp = await client.get(url, headers=headers, params=params)
+        if resp.status_code != 200:
+            error_body = resp.text[:300]
+            return Response(
+                content='{"success":false,"error":"HTTP %d: %s"}' % (resp.status_code, error_body),
+                media_type="application/json",
+                status_code=200,
+            )
+        return Response(content=resp.content, media_type=resp.headers.get("content-type", "image/jpeg"))

app/api/v1/router.py

@@ -11,6 +11,7 @@ from app.api.v1 import (
     csv_analysis,
     database,
     embeddings,
+    google_maps,
     json_extract,
     keys_extract,
     qr_decoder,
@@ -51,6 +52,7 @@ api_v1_router.include_router(chat.router, tags=["Chat"])
 api_v1_router.include_router(vector_stores.router, tags=["Vector Stores"])
 api_v1_router.include_router(webhook_socket.router, tags=["Webhook / Socket"])
 api_v1_router.include_router(csv_analysis.router, tags=["CSV Analysis"])
+api_v1_router.include_router(google_maps.router, tags=["Google Maps"])
 api_v1_router.include_router(json_extract.router, tags=["JSON Extractor"])
 api_v1_router.include_router(keys_extract.router, prefix="/json", tags=["Keys Extractor"])
 api_v1_router.include_router(qr_decoder.router, tags=["QR Decoder"])

app/config.py

@@ -95,6 +95,13 @@ class Settings(BaseSettings):
     redis_retry_on_timeout: bool = Field(default=True, alias="REDIS_RETRY_ON_TIMEOUT")
     redis_health_check_interval: int = Field(default=30, alias="REDIS_HEALTH_CHECK_INTERVAL")
 
+    # Google Maps / GCP settings
+    gcp_api_key: str = Field(default="", alias="GCP_API_KEY")
+    google_maps_base_url: str = "https://maps.googleapis.com/maps/api"
+    google_maps_places_base_url: str = "https://places.googleapis.com/v1"
+    google_maps_timeout: int = 15
+    google_maps_max_retries: int = 2
+
     # Scheduler settings
     max_http_timeout: float = 300.0
     default_scheduler_timezone: str = "UTC"

app/models/schemas.py

@@ -708,3 +708,178 @@ class WebhookSocketStatsResponse(BaseModel):
     total_messages: int
     total_subscribers: int
     channels_detail: Dict[str, Dict[str, Any]]
+
+
+# ---------------------------------------------------------------------------
+# Google Maps (Geocoding & Places)
+# ---------------------------------------------------------------------------
+
+class GoogleGeocodeRequest(BaseModel):
+    address: str = Field(..., min_length=1, max_length=1000, description="Street address to geocode")
+    region: Optional[str] = Field(None, max_length=2, description="Region biasing (ccTLD two-character value, e.g. 'uk', 'us')")
+    language: Optional[str] = Field(None, max_length=10, description="Language code for results")
+    bounds: Optional[str] = Field(None, description="Bounding box to bias results: 'lat_sw,lng_sw|lat_ne,lng_ne'")
+
+class GoogleReverseGeocodeRequest(BaseModel):
+    latlng: str = Field(..., pattern=r"^-?\d+\.?\d*,-?\d+\.?\d*$", description="Latitude,Longitude to reverse geocode (e.g. '40.714224,-73.961452')")
+    language: Optional[str] = Field(None, max_length=10, description="Language code for results")
+    result_type: Optional[str] = Field(None, description="Restrict to specific address types (comma-separated)")
+    location_type: Optional[str] = Field(None, description="Restrict to specific location types (comma-separated: ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER, APPROXIMATE)")
+
+class GoogleGeocodeResult(BaseModel):
+    formatted_address: str
+    place_id: str
+    latitude: float
+    longitude: float
+    location_type: str = ""
+    address_components: List[Dict[str, Any]] = []
+    types: List[str] = []
+
+class GoogleGeocodeResponse(BaseModel):
+    success: bool
+    time_ms: float
+    results: List[GoogleGeocodeResult] = []
+    count: int = 0
+    error: Optional[str] = None
+
+class GooglePlacesSearchRequest(BaseModel):
+    query: str = Field(..., min_length=1, max_length=1000, description="Text query for place search")
+    region: Optional[str] = Field(None, max_length=2, description="Region biasing (ccTLD)")
+    language: Optional[str] = Field(None, max_length=10, description="Language code")
+    min_price: Optional[int] = Field(None, ge=0, le=4, description="Minimum price level (0=free, 4=most expensive)")
+    max_price: Optional[int] = Field(None, ge=0, le=4, description="Maximum price level (0=free, 4=most expensive)")
+    open_now: Optional[bool] = Field(None, description="Only return places that are open now")
+    type: Optional[str] = Field(None, description="Restrict to a specific place type (e.g. 'restaurant', 'cafe')")
+    radius: Optional[int] = Field(None, ge=1, le=50000, description="Search radius in meters (max 50000)")
+    page_token: Optional[str] = Field(None, description="Token for pagination (from previous response next_page_token)")
+    page_size: Optional[int] = Field(None, ge=1, le=200, description="Number of results per page (1-200)")
+    min_rating: Optional[float] = Field(None, ge=0.0, le=5.0, description="Minimum rating filter")
+
+class GooglePlacesNearbyRequest(BaseModel):
+    location: str = Field(..., pattern=r"^-?\d+\.?\d*,-?\d+\.?\d*$", description="Latitude,Longitude of the center point")
+    radius: int = Field(default=1000, ge=1, le=50000, description="Search radius in meters (max 50000)")
+    keyword: Optional[str] = Field(None, max_length=500, description="Keyword to match against place names/types")
+    language: Optional[str] = Field(None, max_length=10, description="Language code")
+    min_price: Optional[int] = Field(None, ge=0, le=4, description="Minimum price level")
+    max_price: Optional[int] = Field(None, ge=0, le=4, description="Maximum price level")
+    open_now: Optional[bool] = Field(None, description="Only return places that are open now")
+    type: Optional[str] = Field(None, description="Restrict to a specific place type")
+    page_token: Optional[str] = Field(None, description="Token for pagination (from previous response next_page_token)")
+    page_size: Optional[int] = Field(None, ge=1, le=200, description="Number of results per page (1-200)")
+    rank_preference: Optional[str] = Field(None, pattern="^(POPULARITY|DISTANCE)$", description="Ranking preference: POPULARITY or DISTANCE")
+
+class GooglePlaceDetailsRequest(BaseModel):
+    place_id: str = Field(..., min_length=1, max_length=500, description="Google Place ID to fetch details for")
+    region: Optional[str] = Field(None, max_length=2, description="Region biasing")
+    language: Optional[str] = Field(None, max_length=10, description="Language code")
+    fields: Optional[str] = Field(None, description="Comma-separated fields to include (default: all)")
+
+class GooglePlacePhoto(BaseModel):
+    photo_reference: str
+    height: int
+    width: int
+    html_attributions: List[str] = []
+
+class GooglePlaceResult(BaseModel):
+    place_id: str
+    name: str
+    formatted_address: str = ""
+    latitude: float = 0.0
+    longitude: float = 0.0
+    rating: Optional[float] = None
+    user_ratings_total: Optional[int] = None
+    price_level: Optional[int] = None
+    types: List[str] = []
+    vicinity: str = ""
+    business_status: Optional[str] = None
+    photos: List[GooglePlacePhoto] = []
+    plus_code: Optional[str] = None
+    icon: Optional[str] = None
+    opening_hours: Optional[Dict[str, Any]] = None
+    website: Optional[str] = None
+    formatted_phone_number: Optional[str] = None
+    international_phone_number: Optional[str] = None
+    google_maps_uri: Optional[str] = None
+
+class GooglePlacesSearchResponse(BaseModel):
+    success: bool
+    time_ms: float
+    results: List[GooglePlaceResult] = []
+    count: int = 0
+    next_page_token: Optional[str] = None
+    error: Optional[str] = None
+
+class GooglePlacesNearbyResponse(BaseModel):
+    success: bool
+    time_ms: float
+    results: List[GooglePlaceResult] = []
+    count: int = 0
+    next_page_token: Optional[str] = None
+    error: Optional[str] = None
+
+class GooglePlaceDetailsResponse(BaseModel):
+    success: bool
+    time_ms: float
+    result: Optional[GooglePlaceResult] = None
+    error: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Google Places Autocomplete
+# ---------------------------------------------------------------------------
+
+class GooglePlaceAutocompleteRequest(BaseModel):
+    input: str = Field(..., min_length=1, max_length=1000, description="Text string to search for")
+    offset: Optional[int] = Field(None, ge=1, description="Character position to start matching within input")
+    origin: Optional[str] = Field(None, pattern=r"^-?\d+\.?\d*,-?\d+\.?\d*$", description="Origin lat,lng for distance-biased results")
+    location: Optional[str] = Field(None, pattern=r"^-?\d+\.?\d*,-?\d+\.?\d*$", description="Point around which to bias results")
+    radius: Optional[int] = Field(None, ge=1, le=50000, description="Radius in meters from location (max 50000)")
+    language: Optional[str] = Field(None, max_length=10, description="Language code for results")
+    types: Optional[str] = Field(None, description="Place types to restrict results (geocode|address|establishment|(regions)|(cities))")
+    components: Optional[str] = Field(None, description="Component filters (e.g. 'country:IN|country:US')")
+    strictbounds: Optional[bool] = Field(None, description="If true, only return places strictly within location/radius")
+    sessiontoken: Optional[str] = Field(None, description="Random string to group autocomplete requests into a session for billing")
+
+class GoogleQueryAutocompleteRequest(BaseModel):
+    input: str = Field(..., min_length=1, max_length=1000, description="Text string to search for")
+    offset: Optional[int] = Field(None, ge=1, description="Character position to start matching within input")
+    location: Optional[str] = Field(None, pattern=r"^-?\d+\.?\d*,-?\d+\.?\d*$", description="Point around which to bias results")
+    radius: Optional[int] = Field(None, ge=1, le=50000, description="Radius in meters from location (max 50000)")
+    language: Optional[str] = Field(None, max_length=10, description="Language code for results")
+
+class GoogleAutocompleteTerm(BaseModel):
+    offset: int
+    value: str
+
+class GoogleAutocompleteMatchedSubstring(BaseModel):
+    offset: int
+    length: int
+
+class GoogleAutocompleteStructuredFormatting(BaseModel):
+    main_text: str
+    main_text_matched_substrings: List[GoogleAutocompleteMatchedSubstring] = []
+    secondary_text: str = ""
+    secondary_text_matched_substrings: List[GoogleAutocompleteMatchedSubstring] = []
+
+class GoogleAutocompletePrediction(BaseModel):
+    description: str
+    place_id: str
+    structured_formatting: Optional[GoogleAutocompleteStructuredFormatting] = None
+    terms: List[GoogleAutocompleteTerm] = []
+    types: List[str] = []
+    matched_substrings: List[GoogleAutocompleteMatchedSubstring] = []
+    distance_meters: Optional[int] = None
+
+class GooglePlaceAutocompleteResponse(BaseModel):
+    success: bool
+    time_ms: float
+    predictions: List[GoogleAutocompletePrediction] = []
+    count: int = 0
+    error: Optional[str] = None
+
+class GoogleQueryAutocompleteResponse(BaseModel):
+    success: bool
+    time_ms: float
+    predictions: List[GoogleAutocompletePrediction] = []
+    count: int = 0
+    error: Optional[str] = None

app/services/google_maps_service.py

@@ -0,0 +1,398 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Dict, Optional
+
+import httpx
+
+from app.config import get_settings
+
+_logger = logging.getLogger(__name__)
+_settings = get_settings()
+
+
+PRICE_LEVEL_MAP: dict[str, int] = {
+    "PRICE_LEVEL_UNSPECIFIED": 0,
+    "PRICE_LEVEL_FREE": 0,
+    "PRICE_LEVEL_INEXPENSIVE": 1,
+    "PRICE_LEVEL_MODERATE": 2,
+    "PRICE_LEVEL_EXPENSIVE": 3,
+    "PRICE_LEVEL_VERY_EXPENSIVE": 4,
+}
+
+DEFAULT_SEARCH_FIELD_MASK = (
+    "places.id,places.displayName,places.formattedAddress,"
+    "places.location,places.rating,places.userRatingCount,"
+    "places.priceLevel,places.types,places.businessStatus,"
+    "places.photos,places.plusCode,places.shortFormattedAddress,"
+    "places.regularOpeningHours,places.websiteUri,"
+    "places.internationalPhoneNumber,places.nationalPhoneNumber,"
+    "places.googleMapsUri,places.iconMaskBaseUri"
+)
+
+DEFAULT_DETAILS_FIELD_MASK = (
+    "id,displayName,formattedAddress,location,rating,userRatingCount,"
+    "priceLevel,types,businessStatus,photos,plusCode,shortFormattedAddress,"
+    "regularOpeningHours,currentOpeningHours,websiteUri,"
+    "internationalPhoneNumber,nationalPhoneNumber,googleMapsUri,"
+    "iconMaskBaseUri,editorialSummary"
+)
+
+DEFAULT_AUTOCOMPLETE_FIELD_MASK = (
+    "suggestions.placePrediction.text.text,"
+    "suggestions.placePrediction.placeId,"
+    "suggestions.placePrediction.types,"
+    "suggestions.placePrediction.distanceMeters,"
+    "suggestions.queryPrediction.text.text"
+)
+
+
+class GoogleMapsService:
+
+    def __init__(self) -> None:
+        self._base_url: str = _settings.google_maps_base_url
+        self._places_base_url: str = _settings.google_maps_places_base_url
+        self._timeout: int = _settings.google_maps_timeout
+        self._max_retries: int = _settings.google_maps_max_retries
+
+    # -----------------------------------------------------------------------
+    # Geocoding — still uses the legacy Google Geocoding API
+    # -----------------------------------------------------------------------
+
+    async def geocode(self, address: str, region: Optional[str] = None,
+                      language: Optional[str] = None, bounds: Optional[str] = None,
+                      api_key: Optional[str] = None) -> Dict[str, Any]:
+        if not api_key:
+            raise ValueError("Google API key is missing")
+        params: Dict[str, Any] = {
+            "address": address,
+            "key": api_key,
+        }
+        if region:
+            params["region"] = region
+        if language:
+            params["language"] = language
+        if bounds:
+            params["bounds"] = bounds
+
+        return await self._call_api("/geocode/json", params)
+
+    async def reverse_geocode(self, latlng: str, language: Optional[str] = None,
+                              result_type: Optional[str] = None,
+                              location_type: Optional[str] = None,
+                              api_key: Optional[str] = None) -> Dict[str, Any]:
+        if not api_key:
+            raise ValueError("Google API key is missing")
+        params: Dict[str, Any] = {
+            "latlng": latlng,
+            "key": api_key,
+        }
+        if language:
+            params["language"] = language
+        if result_type:
+            params["result_type"] = result_type
+        if location_type:
+            params["location_type"] = location_type
+
+        return await self._call_api("/geocode/json", params)
+
+    # -----------------------------------------------------------------------
+    # Places API (New) — places.googleapis.com/v1
+    # -----------------------------------------------------------------------
+
+    def _price_levels_from_range(self, min_price: Optional[int], max_price: Optional[int]) -> list[str]:
+        levels = ["PRICE_LEVEL_FREE", "PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE", "PRICE_LEVEL_EXPENSIVE", "PRICE_LEVEL_VERY_EXPENSIVE"]
+        lo = max(0, min_price if min_price is not None else 0)
+        hi = min(4, max_price if max_price is not None else 4)
+        if lo > hi:
+            lo, hi = hi, lo
+        return [levels[i] for i in range(lo, hi + 1)]
+
+    async def places_search(self, query: str, region: Optional[str] = None,
+                            language: Optional[str] = None, min_price: Optional[int] = None,
+                            max_price: Optional[int] = None, open_now: Optional[bool] = None,
+                            type_filter: Optional[str] = None,
+                            radius: Optional[int] = None,
+                            page_token: Optional[str] = None,
+                            page_size: Optional[int] = None,
+                            min_rating: Optional[float] = None,
+                            api_key: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {
+            "textQuery": query,
+        }
+        if page_token:
+            body["pageToken"] = page_token
+        else:
+            body["maxResultCount"] = page_size or 10
+        if region:
+            body["regionCode"] = region.upper()
+        if language:
+            body["languageCode"] = language
+        if type_filter:
+            body["includedType"] = type_filter
+        if min_price is not None or max_price is not None:
+            body["priceLevels"] = self._price_levels_from_range(min_price, max_price)
+        if open_now is not None:
+            body["openNow"] = open_now
+        if min_rating is not None:
+            body["minRating"] = min_rating
+
+        return await self._call_places_api("POST", "/places:searchText", body=body, field_mask=DEFAULT_SEARCH_FIELD_MASK, api_key=api_key)
+
+    async def places_nearby(self, location: str, radius: int = 1000,
+                            keyword: Optional[str] = None, language: Optional[str] = None,
+                            min_price: Optional[int] = None, max_price: Optional[int] = None,
+                            open_now: Optional[bool] = None,
+                            type_filter: Optional[str] = None,
+                            page_token: Optional[str] = None,
+                            page_size: Optional[int] = None,
+                            rank_preference: Optional[str] = None,
+                            api_key: Optional[str] = None) -> Dict[str, Any]:
+        parts = location.split(",")
+        lat = float(parts[0].strip())
+        lng = float(parts[1].strip())
+
+        body: Dict[str, Any] = {
+            "locationRestriction": {
+                "circle": {
+                    "center": {"latitude": lat, "longitude": lng},
+                    "radius": float(radius),
+                }
+            },
+        }
+        if page_token:
+            body["pageToken"] = page_token
+        else:
+            body["maxResultCount"] = page_size or 10
+        if type_filter:
+            body["includedTypes"] = type_filter.split(",")
+        if keyword:
+            body["includedPrimaryTypes"] = [keyword]
+        if language:
+            body["languageCode"] = language
+        if min_price is not None or max_price is not None:
+            body["priceLevels"] = self._price_levels_from_range(min_price, max_price)
+        if open_now is not None:
+            body["openNow"] = open_now
+        if rank_preference:
+            body["rankPreference"] = rank_preference.upper()
+
+        return await self._call_places_api("POST", "/places:searchNearby", body=body, field_mask=DEFAULT_SEARCH_FIELD_MASK, api_key=api_key)
+
+    async def place_autocomplete(self, input: str, offset: Optional[int] = None,
+                                 origin: Optional[str] = None,
+                                 location: Optional[str] = None,
+                                 radius: Optional[int] = None,
+                                 language: Optional[str] = None,
+                                 types: Optional[str] = None,
+                                 components: Optional[str] = None,
+                                 strictbounds: Optional[bool] = None,
+                                 sessiontoken: Optional[str] = None,
+                                 api_key: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {
+            "input": input,
+        }
+        if language:
+            body["languageCode"] = language
+        if offset is not None:
+            body["inputOffset"] = offset
+        if location:
+            parts = location.split(",")
+            body["locationBias"] = {
+                "circle": {
+                    "center": {"latitude": float(parts[0].strip()), "longitude": float(parts[1].strip())},
+                    "radius": float(radius or 50000),
+                }
+            }
+        if origin:
+            parts = origin.split(",")
+            body["origin"] = {"latitude": float(parts[0].strip()), "longitude": float(parts[1].strip())}
+        if types:
+            mapped = []
+            for t in types.replace("(", "").replace(")", "").split("|"):
+                t = t.strip()
+                if t == "cities":
+                    t = "locality"
+                mapped.append(t)
+            body["includedPrimaryTypes"] = mapped
+        if components:
+            parts_list = [c.split(":") for c in components.split("|") if ":" in c]
+            for pair in parts_list:
+                key, val = pair[0].strip(), pair[1].strip()
+                if key == "country":
+                    body["regionCode"] = val.upper()
+        if sessiontoken:
+            body["sessionToken"] = sessiontoken
+
+        field_mask = "suggestions.placePrediction.text.text,suggestions.placePrediction.placeId,suggestions.placePrediction.types,suggestions.placePrediction.distanceMeters,suggestions.placePrediction.structuredFormat.mainText.text,suggestions.placePrediction.structuredFormat.secondaryText.text"
+
+        return await self._call_places_api("POST", "/places:autocomplete", body=body, field_mask=field_mask, api_key=api_key)
+
+    async def query_autocomplete(self, input: str, offset: Optional[int] = None,
+                                 location: Optional[str] = None,
+                                 radius: Optional[int] = None,
+                                 language: Optional[str] = None,
+                                 api_key: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {
+            "input": input,
+            "includeQueryPredictions": True,
+        }
+        if language:
+            body["languageCode"] = language
+        if offset is not None:
+            body["inputOffset"] = offset
+        if location:
+            parts = location.split(",")
+            body["locationBias"] = {
+                "circle": {
+                    "center": {"latitude": float(parts[0].strip()), "longitude": float(parts[1].strip())},
+                    "radius": float(radius or 50000),
+                }
+            }
+
+        field_mask = "suggestions.placePrediction.text.text,suggestions.placePrediction.placeId,suggestions.placePrediction.types,suggestions.placePrediction.distanceMeters,suggestions.queryPrediction.text.text"
+
+        return await self._call_places_api("POST", "/places:autocomplete", body=body, field_mask=field_mask, api_key=api_key)
+
+    async def place_details(self, place_id: str, region: Optional[str] = None,
+                            language: Optional[str] = None,
+                            fields: Optional[str] = None,
+                            api_key: Optional[str] = None) -> Dict[str, Any]:
+        path = f"/places/{place_id}"
+        field_mask = fields or DEFAULT_DETAILS_FIELD_MASK
+        params = {}
+        if language:
+            params["languageCode"] = language
+
+        return await self._call_places_api("GET", path, params=params, field_mask=field_mask, api_key=api_key)
+
+    # -----------------------------------------------------------------------
+    # Internal — Legacy API (for Geocoding)
+    # -----------------------------------------------------------------------
+
+    async def _call_api(self, path: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        last_error: Optional[str] = None
+
+        for attempt in range(1 + self._max_retries):
+            try:
+                async with httpx.AsyncClient(timeout=self._timeout) as client:
+                    response = await client.get(url, params=params)
+                    response.raise_for_status()
+                    data: Dict[str, Any] = response.json()
+                    return self._normalize_response(data)
+
+            except httpx.TimeoutException:
+                last_error = "Request timed out"
+                _logger.warning("Google Maps API timeout on %s (attempt %d/%d)", path, attempt + 1, 1 + self._max_retries)
+            except httpx.HTTPStatusError as e:
+                last_error = f"HTTP {e.response.status_code}: {e.response.text[:500]}"
+                _logger.warning("Google Maps API HTTP error on %s: %s (attempt %d/%d)", path, last_error, attempt + 1, 1 + self._max_retries)
+                if 400 <= e.response.status_code < 500:
+                    break
+            except httpx.RequestError as e:
+                last_error = f"Request failed: {e}"
+                _logger.warning("Google Maps API request error on %s: %s (attempt %d/%d)", path, last_error, attempt + 1, 1 + self._max_retries)
+            except Exception as e:
+                last_error = f"Unexpected error: {e}"
+                _logger.error("Google Maps API unexpected error on %s: %s", path, last_error)
+                break
+
+            if attempt < self._max_retries:
+                await asyncio.sleep(1.0 * (attempt + 1))
+
+        return {"success": False, "error": last_error or "Unknown error"}
+
+    def _normalize_response(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        status: str = data.get("status", "")
+        error_message: str = data.get("error_message", "")
+
+        if status == "OK" or status == "ZERO_RESULTS":
+            return {
+                "success": True,
+                "status": status,
+                "data": data,
+                "error": None,
+            }
+
+        if status == "OVER_QUERY_LIMIT":
+            return {"success": False, "status": status, "error": "API quota exceeded. Please wait and retry."}
+        if status == "REQUEST_DENIED":
+            return {"success": False, "status": status, "error": f"Request denied: {error_message}"}
+        if status == "INVALID_REQUEST":
+            return {"success": False, "status": status, "error": f"Invalid request: {error_message}"}
+        if status == "NOT_FOUND":
+            return {"success": False, "status": status, "error": "The specified place was not found."}
+
+        return {"success": False, "status": status, "error": error_message or f"Unknown status: {status}"}
+
+    # -----------------------------------------------------------------------
+    # Internal — Places API (New)
+    # -----------------------------------------------------------------------
+
+    async def _call_places_api(self, method: str, path: str,
+                               body: Optional[Dict[str, Any]] = None,
+                               params: Optional[Dict[str, Any]] = None,
+                               field_mask: Optional[str] = None,
+                               api_key: Optional[str] = None) -> Dict[str, Any]:
+        if not api_key:
+            raise ValueError("Google API key is missing")
+        url = f"{self._places_base_url}{path}"
+        headers: Dict[str, str] = {
+            "X-Goog-Api-Key": api_key,
+            "Content-Type": "application/json",
+        }
+        if field_mask:
+            headers["X-Goog-FieldMask"] = field_mask
+
+        last_error: Optional[str] = None
+
+        for attempt in range(1 + self._max_retries):
+            try:
+                async with httpx.AsyncClient(timeout=self._timeout) as client:
+                    if method == "POST":
+                        response = await client.post(url, json=body, headers=headers)
+                    else:
+                        response = await client.get(url, params=params, headers=headers)
+
+                    if response.status_code == 200:
+                        data: Dict[str, Any] = response.json()
+                        return {"success": True, "data": data, "error": None}
+
+                    try:
+                        error_body = response.json()
+                        error_msg = error_body.get("error", {}).get("message", response.text[:500])
+                        error_detail = error_body.get("error", {})
+                        _logger.warning("Places API error on %s: status=%s code=%s message=%s",
+                                       path, response.status_code, error_detail.get("code"), error_detail.get("message"))
+                    except Exception:
+                        error_msg = response.text[:500]
+                        _logger.warning("Places API error on %s: HTTP %s body=%s", path, response.status_code, error_msg)
+                    last_error = f"HTTP {response.status_code}: {error_msg}"
+
+                    if response.status_code == 429:
+                        backoff = 2.0 ** (attempt + 1)
+                        _logger.warning("Places API rate limited on %s, backing off %.1fs", path, backoff)
+                        if attempt < self._max_retries:
+                            await asyncio.sleep(backoff)
+                        continue
+
+                    if 400 <= response.status_code < 500:
+                        break
+
+            except httpx.TimeoutException:
+                last_error = "Request timed out"
+                _logger.warning("Places API timeout on %s (attempt %d/%d)", path, attempt + 1, 1 + self._max_retries)
+            except httpx.RequestError as e:
+                last_error = f"Request failed: {e}"
+                _logger.warning("Places API request error on %s: %s (attempt %d/%d)", path, last_error, attempt + 1, 1 + self._max_retries)
+            except Exception as e:
+                last_error = f"Unexpected error: {e}"
+                _logger.error("Places API unexpected error on %s: %s", path, last_error)
+                break
+
+            if attempt < self._max_retries:
+                await asyncio.sleep(1.0 * (attempt + 1))
+
+        return {"success": False, "error": last_error or "Unknown error"}