@prismer/runtime 2.0.8 → 2.2.63

package/built-in-skills/prismer-maps/scripts/maps_client.py

@@ -0,0 +1,1324 @@
+#!/usr/bin/env python3
+"""
+maps_client.py - CLI tool for maps, geocoding, routing, POI search, and more.
+Uses only Python stdlib. Data from OpenStreetMap/Nominatim, Overpass API, OSRM,
+and TimeAPI.io.
+
+Commands:
+  search     - Geocode a place name to coordinates
+  reverse    - Reverse geocode coordinates to an address
+  nearby     - Find nearby POIs by category
+  distance   - Road distance and travel time between two places
+  directions - Turn-by-turn directions between two places
+  timezone   - Timezone info for coordinates
+  bbox       - Find POIs within a bounding box
+  area       - Get bounding box and area info for a named place
+"""
+
+import argparse
+import json
+import math
+import os
+from pathlib import Path
+import sqlite3
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+USER_AGENT = os.environ.get("PRISMER_MAPS_USER_AGENT", "PrismerMaps/1.0")
+DATA_SOURCE = "OpenStreetMap/Nominatim"
+
+NOMINATIM_SEARCH  = "https://nominatim.openstreetmap.org/search"
+NOMINATIM_REVERSE = "https://nominatim.openstreetmap.org/reverse"
+# Public Overpass endpoints. We try them in order so a single server
+# outage doesn't break the skill — kumi.systems is a well-known mirror.
+OVERPASS_URLS = [
+    "https://overpass-api.de/api/interpreter",
+    "https://overpass.kumi.systems/api/interpreter",
+]
+# Backward-compat alias for any caller that imports OVERPASS_API directly.
+OVERPASS_API      = OVERPASS_URLS[0]
+OSRM_BASE         = "https://router.project-osrm.org/route/v1"
+TIMEAPI_BASE      = "https://timeapi.io/api/timezone/coordinate"
+
+# Seconds to sleep between Nominatim requests (ToS requirement)
+NOMINATIM_RATE_LIMIT = 1.0
+
+# Maximum retries for HTTP errors
+MAX_RETRIES = 3
+RETRY_DELAY = 2.0  # seconds
+
+# Category -> (OSM tag key, OSM tag value)
+CATEGORY_TAGS = {
+    # Food & Drink
+    "restaurant":        ("amenity", "restaurant"),
+    "cafe":              ("amenity", "cafe"),
+    "bar":               ("amenity", "bar"),
+    # bakery is tagged as shop=bakery in the OSM wiki, but some mappers use
+    # amenity=bakery. Search both so small indie bakeries aren't missed.
+    "bakery":            [("shop", "bakery"), ("amenity", "bakery")],
+    "convenience_store": ("shop",    "convenience"),
+    # Health
+    "hospital":          ("amenity", "hospital"),
+    "pharmacy":          ("amenity", "pharmacy"),
+    "dentist":           ("amenity", "dentist"),
+    "doctor":            ("amenity", "doctors"),
+    "veterinary":        ("amenity", "veterinary"),
+    # Accommodation
+    "hotel":             ("tourism", "hotel"),
+    "guest_house":       ("tourism", "guest_house"),
+    "camp_site":         ("tourism", "camp_site"),
+    # Shopping & Services
+    "supermarket":       ("shop",    "supermarket"),
+    "bookshop":          ("shop",    "books"),
+    "laundry":           ("shop",    "laundry"),
+    # Finance
+    "atm":               ("amenity", "atm"),
+    "bank":              ("amenity", "bank"),
+    # Transport
+    "gas_station":       ("amenity", "fuel"),
+    "parking":           ("amenity", "parking"),
+    "airport":           ("aeroway", "aerodrome"),
+    "train_station":     ("railway", "station"),
+    "bus_stop":          ("highway", "bus_stop"),
+    "taxi":              ("amenity", "taxi"),
+    "car_wash":          ("amenity", "car_wash"),
+    "car_rental":        ("amenity", "car_rental"),
+    "bicycle_rental":    ("amenity", "bicycle_rental"),
+    # Culture & Entertainment
+    "museum":            ("tourism", "museum"),
+    "cinema":            ("amenity", "cinema"),
+    "theatre":           ("amenity", "theatre"),
+    "nightclub":         ("amenity", "nightclub"),
+    "zoo":               ("tourism", "zoo"),
+    # Education
+    "school":            ("amenity", "school"),
+    "university":        ("amenity", "university"),
+    "library":           ("amenity", "library"),
+    # Public Services
+    "police":            ("amenity", "police"),
+    "fire_station":      ("amenity", "fire_station"),
+    "post_office":       ("amenity", "post_office"),
+    # Religion
+    "church":            ("amenity", "place_of_worship"),  # refined by religion tag
+    "mosque":            ("amenity", "place_of_worship"),
+    "synagogue":         ("amenity", "place_of_worship"),
+    # Recreation
+    "park":              ("leisure", "park"),
+    "gym":               ("leisure", "fitness_centre"),
+    "swimming_pool":     ("leisure", "swimming_pool"),
+    "playground":        ("leisure", "playground"),
+    "stadium":           ("leisure", "stadium"),
+}
+
+# Religion-specific overrides for place_of_worship categories
+RELIGION_FILTER = {
+    "church":    "christian",
+    "mosque":    "muslim",
+    "synagogue": "jewish",
+}
+
+VALID_CATEGORIES = sorted(CATEGORY_TAGS.keys())
+
+
+def _tags_for(category):
+    """Return the CATEGORY_TAGS entry as a list of (key, value) pairs.
+
+    Most categories map to a single (tag_key, tag_val) tuple, but some
+    (e.g. ``bakery``) are tagged under more than one OSM key and are
+    represented as a list of tuples. Normalise both forms to a list.
+    """
+    entry = CATEGORY_TAGS[category]
+    if isinstance(entry, list):
+        return list(entry)
+    return [entry]
+
+OSRM_PROFILES = {
+    "driving": "driving",
+    "walking": "foot",
+    "cycling": "bike",
+}
+
+# ---------------------------------------------------------------------------
+# Output helpers
+# ---------------------------------------------------------------------------
+
+def print_json(data):
+    """Print data as pretty-printed JSON to stdout."""
+    print(json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def error_exit(message, code=1):
+    """Print an error result as JSON and exit."""
+    print_json({"error": message, "status": "error"})
+    sys.exit(code)
+
+
+# ---------------------------------------------------------------------------
+# HTTP helpers
+# ---------------------------------------------------------------------------
+
+def reserve_nominatim_slot(now=None):
+    """Atomically reserve a host-user slot shared by separate CLI processes."""
+    path = Path(os.environ.get('PRISMER_MAPS_RATE_DB', str(Path.home() / '.cache/prismer/maps-rate.sqlite')))
+    if path.is_symlink():
+        raise ValueError('refusing symlink rate database')
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    fd = os.open(path, os.O_CREAT | os.O_RDWR, 0o600)
+    os.close(fd)
+    db = sqlite3.connect(path, timeout=30)
+    try:
+        db.execute('BEGIN IMMEDIATE')
+        db.execute('CREATE TABLE IF NOT EXISTS rate (id INTEGER PRIMARY KEY, next REAL)')
+        now = time.time() if now is None else now
+        row = db.execute('SELECT next FROM rate WHERE id=1').fetchone()
+        slot = max(now, row[0] if row else now)
+        db.execute('INSERT OR REPLACE INTO rate VALUES (1,?)', (slot + NOMINATIM_RATE_LIMIT,))
+        db.commit()
+        return slot - now
+    finally:
+        db.close()
+
+
+def http_get(url, params=None, retries=MAX_RETRIES, silent=False):
+    """
+    Perform an HTTP GET request, returning parsed JSON.
+    Adds the required User-Agent header. Retries on transient errors.
+    If silent=True, raises RuntimeError instead of calling error_exit.
+    """
+    if params:
+        url = url + "?" + urllib.parse.urlencode(params)
+
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+
+    last_error = None
+    for attempt in range(1, retries + 1):
+        try:
+            if urllib.parse.urlparse(url).hostname == 'nominatim.openstreetmap.org':
+                time.sleep(reserve_nominatim_slot())
+            with urllib.request.urlopen(req, timeout=15) as resp:
+                raw = resp.read().decode("utf-8")
+                return json.loads(raw)
+        except urllib.error.HTTPError as exc:
+            last_error = f"HTTP {exc.code}: {exc.reason} for {url}"
+            if exc.code in {429, 503, 502, 504}:
+                time.sleep(RETRY_DELAY * attempt)
+            else:
+                if silent:
+                    raise RuntimeError(last_error)
+                error_exit(last_error)
+        except urllib.error.URLError as exc:
+            last_error = f"URL error: {exc.reason}"
+            time.sleep(RETRY_DELAY * attempt)
+        except json.JSONDecodeError as exc:
+            last_error = f"JSON parse error: {exc}"
+            time.sleep(RETRY_DELAY * attempt)
+
+    msg = f"Request failed after {retries} attempts. Last error: {last_error}"
+    if silent:
+        raise RuntimeError(msg)
+    error_exit(msg)
+
+
+def http_get_text(url, params=None, retries=MAX_RETRIES, silent=False):
+    """
+    Like http_get but returns raw text instead of parsed JSON.
+    Useful for APIs that may return non-JSON responses.
+    """
+    if params:
+        url = url + "?" + urllib.parse.urlencode(params)
+
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+
+    last_error = None
+    for attempt in range(1, retries + 1):
+        try:
+            with urllib.request.urlopen(req, timeout=15) as resp:
+                return resp.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            last_error = f"HTTP {exc.code}: {exc.reason} for {url}"
+            if exc.code in {429, 503, 502, 504}:
+                time.sleep(RETRY_DELAY * attempt)
+            else:
+                if silent:
+                    raise RuntimeError(last_error)
+                error_exit(last_error)
+        except urllib.error.URLError as exc:
+            last_error = f"URL error: {exc.reason}"
+            time.sleep(RETRY_DELAY * attempt)
+
+    msg = f"Request failed after {retries} attempts. Last error: {last_error}"
+    if silent:
+        raise RuntimeError(msg)
+    error_exit(msg)
+
+
+def http_post(url, data_str, retries=MAX_RETRIES):
+    """
+    Perform an HTTP POST with a plain-text body (for Overpass QL).
+    Returns parsed JSON.
+    """
+    encoded = data_str.encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=encoded,
+        headers={
+            "User-Agent": USER_AGENT,
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+    )
+
+    last_error = None
+    for attempt in range(1, retries + 1):
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                raw = resp.read().decode("utf-8")
+                return json.loads(raw)
+        except urllib.error.HTTPError as exc:
+            last_error = f"HTTP {exc.code}: {exc.reason}"
+            if exc.code in {429, 503, 502, 504}:
+                time.sleep(RETRY_DELAY * attempt)
+            else:
+                raise RuntimeError(last_error)
+        except urllib.error.URLError as exc:
+            last_error = f"URL error: {exc.reason}"
+            time.sleep(RETRY_DELAY * attempt)
+        except json.JSONDecodeError as exc:
+            last_error = f"JSON parse error: {exc}"
+            time.sleep(RETRY_DELAY * attempt)
+
+    raise RuntimeError(f"POST failed after {retries} attempts. Last error: {last_error}")
+
+
+def overpass_query(query):
+    """POST an Overpass QL query, trying each URL in OVERPASS_URLS in turn.
+
+    A single public Overpass mirror can be rate-limited or down; trying the
+    next mirror before giving up turns a flaky outage into a retry. Returns
+    parsed JSON. Falls through to error_exit if every mirror fails.
+    """
+    post_data = "data=" + urllib.parse.quote(query)
+    last_error = None
+    for url in OVERPASS_URLS:
+        try:
+            return http_post(url, post_data, retries=1)
+        except SystemExit:
+            # error_exit inside http_post — keep trying the next mirror.
+            last_error = f"mirror {url} exhausted retries"
+            continue
+        except Exception as exc:
+            last_error = f"{url}: {exc}"
+            continue
+    error_exit(
+        f"All Overpass mirrors failed. Last error: {last_error or 'unknown'}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Geo math
+# ---------------------------------------------------------------------------
+
+def haversine_m(lat1, lon1, lat2, lon2):
+    """Return distance in metres between two lat/lon points (Haversine)."""
+    R = 6_371_000  # Earth mean radius in metres
+    phi1 = math.radians(lat1)
+    phi2 = math.radians(lat2)
+    dphi = math.radians(lat2 - lat1)
+    dlam = math.radians(lon2 - lon1)
+    a = (math.sin(dphi / 2) ** 2
+         + math.cos(phi1) * math.cos(phi2) * math.sin(dlam / 2) ** 2)
+    return 2 * R * math.atan2(math.sqrt(a), math.sqrt(1 - a))
+
+
+# ---------------------------------------------------------------------------
+# Nominatim helpers
+# ---------------------------------------------------------------------------
+
+def nominatim_search(query, limit=5):
+    """Geocode a free-text query. Returns list of result dicts."""
+    params = {
+        "q":              query,
+        "format":         "json",
+        "limit":          limit,
+        "addressdetails": 1,
+    }
+    time.sleep(NOMINATIM_RATE_LIMIT)
+    return http_get(NOMINATIM_SEARCH, params=params)
+
+
+def nominatim_reverse(lat, lon):
+    """Reverse geocode lat/lon. Returns a single result dict."""
+    params = {
+        "lat":            lat,
+        "lon":            lon,
+        "format":         "json",
+        "addressdetails": 1,
+    }
+    time.sleep(NOMINATIM_RATE_LIMIT)
+    return http_get(NOMINATIM_REVERSE, params=params)
+
+
+def geocode_single(query):
+    """
+    Geocode a query and return (lat, lon, display_name).
+    Exits with error if nothing found.
+    """
+    results = nominatim_search(query, limit=1)
+    if not results:
+        error_exit(f"Could not geocode: {query}")
+    r = results[0]
+    return float(r["lat"]), float(r["lon"]), r.get("display_name", query)
+
+
+# ---------------------------------------------------------------------------
+# Overpass helpers
+# ---------------------------------------------------------------------------
+
+def build_overpass_nearby(tag_key, tag_val, lat, lon, radius, limit,
+                          religion=None, tag_pairs=None):
+    """Build an Overpass QL query for nearby POIs around a point.
+
+    If ``tag_pairs`` is provided, the query unions across every
+    ``(key, value)`` pair (used for categories like ``bakery`` that are
+    tagged under more than one OSM key). Otherwise falls back to the
+    single ``tag_key``/``tag_val`` pair for back-compat.
+    """
+    pairs = tag_pairs if tag_pairs else [(tag_key, tag_val)]
+    religion_filter = ""
+    if religion:
+        religion_filter = f'["religion"="{religion}"]'
+    body_lines = []
+    for k, v in pairs:
+        body_lines.append(
+            f'  node["{k}"="{v}"]{religion_filter}'
+            f'(around:{radius},{lat},{lon});'
+        )
+        body_lines.append(
+            f'  way["{k}"="{v}"]{religion_filter}'
+            f'(around:{radius},{lat},{lon});'
+        )
+    body = "\n".join(body_lines)
+    return (
+        f'[out:json][timeout:25];\n'
+        f'(\n'
+        f'{body}\n'
+        f');\n'
+        f'out center {limit};\n'
+    )
+
+
+def build_overpass_bbox(tag_key, tag_val, south, west, north, east, limit,
+                        religion=None, tag_pairs=None):
+    """Build an Overpass QL query for POIs within a bounding box.
+
+    See ``build_overpass_nearby`` for ``tag_pairs`` semantics.
+    """
+    pairs = tag_pairs if tag_pairs else [(tag_key, tag_val)]
+    religion_filter = ""
+    if religion:
+        religion_filter = f'["religion"="{religion}"]'
+    body_lines = []
+    for k, v in pairs:
+        body_lines.append(
+            f'  node["{k}"="{v}"]{religion_filter}'
+            f'({south},{west},{north},{east});'
+        )
+        body_lines.append(
+            f'  way["{k}"="{v}"]{religion_filter}'
+            f'({south},{west},{north},{east});'
+        )
+    body = "\n".join(body_lines)
+    return (
+        f'[out:json][timeout:25];\n'
+        f'(\n'
+        f'{body}\n'
+        f');\n'
+        f'out center {limit};\n'
+    )
+
+
+def parse_overpass_elements(elements, ref_lat=None, ref_lon=None):
+    """
+    Parse Overpass elements into a clean list of POI dicts.
+    If ref_lat/ref_lon are provided, computes distance and sorts by it.
+    """
+    places = []
+    for el in elements:
+        # Ways have a "center" sub-dict; nodes have lat/lon directly
+        if el["type"] == "way":
+            center = el.get("center", {})
+            el_lat = center.get("lat")
+            el_lon = center.get("lon")
+        else:
+            el_lat = el.get("lat")
+            el_lon = el.get("lon")
+
+        if el_lat is None or el_lon is None:
+            continue
+
+        tags = el.get("tags", {})
+        name = tags.get("name") or tags.get("name:en") or ""
+
+        # Build a short address from available tags
+        addr_parts = []
+        for part_key in ("addr:housenumber", "addr:street", "addr:city"):
+            val = tags.get(part_key)
+            if val:
+                addr_parts.append(val)
+        address_str = ", ".join(addr_parts) if addr_parts else ""
+
+        place = {
+            "name":     name,
+            "address":  address_str,
+            "lat":      el_lat,
+            "lon":      el_lon,
+            "osm_type": el.get("type", ""),
+            "osm_id":   el.get("id", ""),
+            # Clickable Google Maps link so the agent can render a tap-to-open
+            # URL in chat without composing one downstream.
+            "maps_url": f"https://www.google.com/maps/search/?api=1&query={el_lat},{el_lon}",
+            "tags": {
+                k: v for k, v in tags.items()
+                if k not in {"name", "name:en",
+                             "addr:housenumber", "addr:street", "addr:city"}
+            },
+        }
+
+        # Promote commonly-useful tags to top-level fields so agents can
+        # reference them without digging into the raw ``tags`` dict.
+        for src_key, dst_key in (
+            ("cuisine",        "cuisine"),
+            ("opening_hours",  "hours"),
+            ("phone",          "phone"),
+            ("website",        "website"),
+        ):
+            val = tags.get(src_key)
+            if val:
+                place[dst_key] = val
+
+        if ref_lat is not None and ref_lon is not None:
+            dist_m = haversine_m(ref_lat, ref_lon, el_lat, el_lon)
+            place["distance_m"] = round(dist_m, 1)
+            # With a reference point we can also hand back a directions URL.
+            place["directions_url"] = (
+                f"https://www.google.com/maps/dir/?api=1"
+                f"&origin={ref_lat},{ref_lon}"
+                f"&destination={el_lat},{el_lon}"
+            )
+
+        places.append(place)
+
+    # Sort by distance if available
+    if places and "distance_m" in places[0]:
+        places.sort(key=lambda p: p["distance_m"])
+
+    return places
+
+
+# ---------------------------------------------------------------------------
+# Command: search
+# ---------------------------------------------------------------------------
+
+def cmd_search(args):
+    """Geocode a place name and return top results."""
+    query = " ".join(args.query)
+    raw   = nominatim_search(query, limit=5)
+
+    if not raw:
+        print_json({
+            "query":       query,
+            "results":     [],
+            "count":       0,
+            "data_source": DATA_SOURCE,
+        })
+        return
+
+    results = []
+    for item in raw:
+        bb = item.get("boundingbox", [])
+        results.append({
+            "name":         item.get("name") or item.get("display_name", ""),
+            "display_name": item.get("display_name", ""),
+            "lat":          float(item["lat"]),
+            "lon":          float(item["lon"]),
+            "type":         item.get("type", ""),
+            "category":     item.get("category", ""),
+            "osm_type":     item.get("osm_type", ""),
+            "osm_id":       item.get("osm_id", ""),
+            "bounding_box": {
+                "min_lat": float(bb[0]) if len(bb) > 0 else None,
+                "max_lat": float(bb[1]) if len(bb) > 1 else None,
+                "min_lon": float(bb[2]) if len(bb) > 2 else None,
+                "max_lon": float(bb[3]) if len(bb) > 3 else None,
+            },
+            "importance":   item.get("importance"),
+        })
+
+    print_json({
+        "query":       query,
+        "results":     results,
+        "count":       len(results),
+        "data_source": DATA_SOURCE,
+    })
+
+
+# ---------------------------------------------------------------------------
+# Command: reverse
+# ---------------------------------------------------------------------------
+
+def cmd_reverse(args):
+    """Reverse geocode coordinates to a human-readable address."""
+    try:
+        lat = float(args.lat)
+        lon = float(args.lon)
+    except ValueError:
+        error_exit("LAT and LON must be numeric values.")
+
+    if not (-90 <= lat <= 90):
+        error_exit("Latitude must be between -90 and 90.")
+    if not (-180 <= lon <= 180):
+        error_exit("Longitude must be between -180 and 180.")
+
+    data = nominatim_reverse(lat, lon)
+
+    if "error" in data:
+        error_exit(f"Reverse geocode failed: {data['error']}")
+
+    address = data.get("address", {})
+
+    print_json({
+        "lat":          lat,
+        "lon":          lon,
+        "display_name": data.get("display_name", ""),
+        "address": {
+            "house_number":  address.get("house_number", ""),
+            "road":          address.get("road", ""),
+            "neighbourhood": address.get("neighbourhood", ""),
+            "suburb":        address.get("suburb", ""),
+            "city":          (address.get("city")
+                              or address.get("town")
+                              or address.get("village", "")),
+            "county":        address.get("county", ""),
+            "state":         address.get("state", ""),
+            "postcode":      address.get("postcode", ""),
+            "country":       address.get("country", ""),
+            "country_code":  address.get("country_code", ""),
+        },
+        "osm_type":    data.get("osm_type", ""),
+        "osm_id":      data.get("osm_id", ""),
+        "data_source": DATA_SOURCE,
+    })
+
+
+# ---------------------------------------------------------------------------
+# Command: nearby
+# ---------------------------------------------------------------------------
+
+def cmd_nearby(args):
+    """Find nearby POIs using the Overpass API.
+
+    Accepts either explicit coordinates (``lat``/``lon``) or a free-form
+    address via ``--near`` (auto-geocoded through Nominatim). Supports
+    multiple categories in one call — results are merged, deduplicated
+    by ``osm_type+osm_id``, sorted by distance.
+    """
+    # Resolve the center point. --near takes precedence if provided so the
+    # agent can ask "cafes near Times Square" in one command without having
+    # to geocode first.
+    if getattr(args, "near", None):
+        near_query = " ".join(args.near).strip() if isinstance(args.near, list) else str(args.near).strip()
+        if not near_query:
+            error_exit("--near must be a non-empty address or place name.")
+        lat, lon, _ = geocode_single(near_query)
+    else:
+        try:
+            lat = float(args.lat)
+            lon = float(args.lon)
+        except (TypeError, ValueError):
+            error_exit("Provide numeric LAT and LON, or use --near \"<address>\".")
+
+    # Categories: support both legacy single positional ``category`` and the
+    # new repeatable ``--category`` flag. Users can ask for multiple place
+    # types in one query.
+    categories = []
+    if getattr(args, "category_list", None):
+        categories.extend(args.category_list)
+    if getattr(args, "category", None):
+        categories.append(args.category)
+    # Deduplicate, preserve order, lower-case.
+    categories = list(dict.fromkeys(c.lower() for c in categories if c))
+    if not categories:
+        error_exit("Provide at least one category (positional or --category).")
+    unknown = [c for c in categories if c not in CATEGORY_TAGS]
+    if unknown:
+        error_exit(
+            f"Unknown categor{'ies' if len(unknown) > 1 else 'y'} "
+            f"{', '.join(repr(c) for c in unknown)}. "
+            f"Valid categories: {', '.join(VALID_CATEGORIES)}"
+        )
+
+    radius = int(args.radius)
+    limit  = int(args.limit)
+    if radius <= 0:
+        error_exit("Radius must be a positive integer (metres).")
+    if limit <= 0:
+        error_exit("Limit must be a positive integer.")
+
+    # Query each category against the Overpass fallback chain, merge results,
+    # dedupe by OSM identity so POIs tagged under multiple categories don't
+    # appear twice.
+    merged = {}
+    for category in categories:
+        tag_pairs = _tags_for(category)
+        religion = RELIGION_FILTER.get(category)
+        query = build_overpass_nearby(None, None, lat, lon, radius, limit,
+                                      religion=religion, tag_pairs=tag_pairs)
+        raw = overpass_query(query)
+        elements = raw.get("elements", [])
+        for place in parse_overpass_elements(elements, ref_lat=lat, ref_lon=lon):
+            place["category"] = category
+            key = (place.get("osm_type", ""), place.get("osm_id", ""))
+            # Prefer the entry that actually has a distance_m attached (first
+            # pass through the ref_lat/ref_lon branch), then first-seen wins.
+            if key not in merged:
+                merged[key] = place
+
+    # Sort merged by distance when we have ref lat/lon, then cap at ``limit``.
+    places = sorted(
+        merged.values(),
+        key=lambda p: p.get("distance_m", float("inf")),
+    )[:limit]
+
+    print_json({
+        "center_lat":  lat,
+        "center_lon":  lon,
+        "categories":  categories,
+        "radius_m":    radius,
+        "count":       len(places),
+        "results":     places,
+        "data_source": DATA_SOURCE,
+    })
+
+
+# ---------------------------------------------------------------------------
+# Command: distance
+# ---------------------------------------------------------------------------
+
+def cmd_distance(args):
+    """Calculate road distance and travel time between two places."""
+    origin_query      = " ".join(args.origin)
+    destination_query = " ".join(args.to)
+    mode              = args.mode.lower()
+
+    if mode not in OSRM_PROFILES:
+        error_exit(f"Invalid mode '{mode}'. Choose from: {', '.join(OSRM_PROFILES)}")
+
+    # Geocode origin and destination
+    o_lat, o_lon, o_name = geocode_single(origin_query)
+    d_lat, d_lon, d_name = geocode_single(destination_query)
+
+    profile = OSRM_PROFILES[mode]
+    url = (
+        f"{OSRM_BASE}/{profile}/"
+        f"{o_lon},{o_lat};{d_lon},{d_lat}"
+        f"?overview=false&steps=false"
+    )
+
+    osrm_data = http_get(url)
+
+    if osrm_data.get("code") != "Ok":
+        error_exit(
+            f"OSRM routing failed: "
+            f"{osrm_data.get('message', osrm_data.get('code', 'unknown error'))}"
+        )
+
+    routes = osrm_data.get("routes", [])
+    if not routes:
+        error_exit("No route found between the two locations.")
+
+    route        = routes[0]
+    distance_m   = route.get("distance", 0)
+    duration_s   = route.get("duration", 0)
+    distance_km  = round(distance_m / 1000, 3)
+    duration_min = round(duration_s / 60, 2)
+
+    # Straight-line distance for reference
+    straight_m = haversine_m(o_lat, o_lon, d_lat, d_lon)
+
+    print_json({
+        "origin": {
+            "query":        origin_query,
+            "display_name": o_name,
+            "lat":          o_lat,
+            "lon":          o_lon,
+        },
+        "destination": {
+            "query":        destination_query,
+            "display_name": d_name,
+            "lat":          d_lat,
+            "lon":          d_lon,
+        },
+        "mode":             mode,
+        "distance_km":      distance_km,
+        "distance_m":       round(distance_m, 1),
+        "duration_minutes": duration_min,
+        "duration_seconds": round(duration_s, 1),
+        "straight_line_km": round(straight_m / 1000, 3),
+        "data_source":      DATA_SOURCE,
+    })
+
+
+# ---------------------------------------------------------------------------
+# Command: directions
+# ---------------------------------------------------------------------------
+
+def _format_duration(seconds):
+    """Format seconds into a human-readable string."""
+    if seconds < 60:
+        return f"{round(seconds)}s"
+    minutes = seconds / 60
+    if minutes < 60:
+        return f"{round(minutes, 1)} min"
+    hours = int(minutes // 60)
+    remaining = round(minutes % 60)
+    return f"{hours}h {remaining}min"
+
+
+def _format_distance(metres):
+    """Format metres into a human-readable string."""
+    if metres < 1000:
+        return f"{round(metres)} m"
+    return f"{round(metres / 1000, 2)} km"
+
+
+def cmd_directions(args):
+    """Get turn-by-turn directions between two places via OSRM."""
+    origin_query      = " ".join(args.origin)
+    destination_query = " ".join(args.to)
+    mode              = args.mode.lower()
+
+    if mode not in OSRM_PROFILES:
+        error_exit(f"Invalid mode '{mode}'. Choose from: {', '.join(OSRM_PROFILES)}")
+
+    # Geocode origin and destination
+    o_lat, o_lon, o_name = geocode_single(origin_query)
+    d_lat, d_lon, d_name = geocode_single(destination_query)
+
+    profile = OSRM_PROFILES[mode]
+    url = (
+        f"{OSRM_BASE}/{profile}/"
+        f"{o_lon},{o_lat};{d_lon},{d_lat}"
+        f"?overview=false&steps=true"
+    )
+
+    osrm_data = http_get(url)
+
+    if osrm_data.get("code") != "Ok":
+        error_exit(
+            f"OSRM routing failed: "
+            f"{osrm_data.get('message', osrm_data.get('code', 'unknown error'))}"
+        )
+
+    routes = osrm_data.get("routes", [])
+    if not routes:
+        error_exit("No route found between the two locations.")
+
+    route        = routes[0]
+    distance_m   = route.get("distance", 0)
+    duration_s   = route.get("duration", 0)
+
+    # Extract steps from all legs
+    steps = []
+    step_num = 0
+    for leg in route.get("legs", []):
+        for step in leg.get("steps", []):
+            maneuver = step.get("maneuver", {})
+            step_dist = step.get("distance", 0)
+            step_dur  = step.get("duration", 0)
+            step_name = step.get("name", "")
+            modifier  = maneuver.get("modifier", "")
+            m_type    = maneuver.get("type", "")
+
+            # Build instruction text
+            if m_type == "depart":
+                instruction = f"Depart on {step_name}" if step_name else "Depart"
+            elif m_type == "arrive":
+                instruction = "Arrive at destination"
+            elif m_type == "turn":
+                instruction = f"Turn {modifier} onto {step_name}" if step_name else f"Turn {modifier}"
+            elif m_type == "new name":
+                instruction = f"Continue onto {step_name}" if step_name else "Continue"
+            elif m_type == "merge":
+                instruction = f"Merge {modifier} onto {step_name}" if step_name else f"Merge {modifier}"
+            elif m_type == "fork":
+                instruction = f"Take the {modifier} fork onto {step_name}" if step_name else f"Take the {modifier} fork"
+            elif m_type == "roundabout":
+                instruction = f"Enter roundabout, exit onto {step_name}" if step_name else "Enter roundabout"
+            elif m_type == "rotary":
+                instruction = f"Enter rotary, exit onto {step_name}" if step_name else "Enter rotary"
+            elif m_type == "end of road":
+                instruction = f"At end of road, turn {modifier} onto {step_name}" if step_name else f"At end of road, turn {modifier}"
+            elif m_type == "continue":
+                instruction = f"Continue {modifier} on {step_name}" if step_name else f"Continue {modifier}"
+            elif m_type == "on ramp":
+                instruction = f"Take ramp onto {step_name}" if step_name else "Take ramp"
+            elif m_type == "off ramp":
+                instruction = f"Take exit onto {step_name}" if step_name else "Take exit"
+            else:
+                instruction = f"{m_type} {modifier} {step_name}".strip()
+
+            step_num += 1
+            steps.append({
+                "step":        step_num,
+                "instruction": instruction,
+                "distance":    _format_distance(step_dist),
+                "distance_m":  round(step_dist, 1),
+                "duration":    _format_duration(step_dur),
+                "duration_s":  round(step_dur, 1),
+                "road_name":   step_name,
+                "maneuver":    m_type,
+            })
+
+    print_json({
+        "origin": {
+            "query":        origin_query,
+            "display_name": o_name,
+            "lat":          o_lat,
+            "lon":          o_lon,
+        },
+        "destination": {
+            "query":        destination_query,
+            "display_name": d_name,
+            "lat":          d_lat,
+            "lon":          d_lon,
+        },
+        "mode":               mode,
+        "total_distance":     _format_distance(distance_m),
+        "total_distance_m":   round(distance_m, 1),
+        "total_duration":     _format_duration(duration_s),
+        "total_duration_s":   round(duration_s, 1),
+        "steps":              steps,
+        "step_count":         len(steps),
+        "data_source":        DATA_SOURCE,
+    })
+
+
+# ---------------------------------------------------------------------------
+# Command: timezone
+# ---------------------------------------------------------------------------
+
+def cmd_timezone(args):
+    """
+    Get timezone information for a lat/lon coordinate.
+
+    Strategy:
+      1. Try TimeAPI.io (free, no key, supports coordinate-based lookup).
+      2. Fallback: derive UTC offset approximation from longitude.
+    """
+    try:
+        lat = float(args.lat)
+        lon = float(args.lon)
+    except ValueError:
+        error_exit("LAT and LON must be numeric values.")
+
+    if not (-90 <= lat <= 90):
+        error_exit("Latitude must be between -90 and 90.")
+    if not (-180 <= lon <= 180):
+        error_exit("Longitude must be between -180 and 180.")
+
+    timezone_str = None
+    timezone_src = None
+    current_time = None
+    utc_offset   = None
+
+    # --- Strategy 1: TimeAPI.io coordinate lookup ---
+    try:
+        params = {"latitude": lat, "longitude": lon}
+        tz_data = http_get(TIMEAPI_BASE, params=params, silent=True)
+        if isinstance(tz_data, dict):
+            timezone_str = tz_data.get("timeZone")
+            current_time = tz_data.get("currentLocalTime")
+            # Build utc_offset from currentUtcOffset if available
+            offset_info = tz_data.get("currentUtcOffset", {})
+            if isinstance(offset_info, dict):
+                oh = offset_info.get("hours", 0)
+                om = abs(offset_info.get("minutes", 0))
+                os_ = offset_info.get("seconds", 0)
+                sign = "+" if oh >= 0 else "-"
+                utc_offset = f"{sign}{abs(oh):02d}:{om:02d}"
+                if os_:
+                    utc_offset = f"{utc_offset}:{os_:02d}"
+            elif tz_data.get("standardUtcOffset"):
+                offset_info2 = tz_data["standardUtcOffset"]
+                if isinstance(offset_info2, dict):
+                    oh = offset_info2.get("hours", 0)
+                    om = abs(offset_info2.get("minutes", 0))
+                    os_ = offset_info2.get("seconds", 0)
+                    sign = "+" if oh >= 0 else "-"
+                    utc_offset = f"{sign}{abs(oh):02d}:{om:02d}"
+                    if os_:
+                        utc_offset = f"{utc_offset}:{os_:02d}"
+            timezone_src = "timeapi.io"
+    except (RuntimeError, KeyError, TypeError):
+        pass  # API may be down; continue to fallback
+
+    # --- Strategy 2: longitude-based UTC offset approximation ---
+    if not timezone_str:
+        approx_offset_h = round(lon / 15)
+        if approx_offset_h >= 0:
+            utc_offset = f"+{approx_offset_h:02d}:00"
+        else:
+            utc_offset = f"-{abs(approx_offset_h):02d}:00"
+        timezone_str = f"UTC{utc_offset}"
+        timezone_src = "longitude approximation (longitude/15)"
+
+    print_json({
+        "lat":          lat,
+        "lon":          lon,
+        "timezone":     timezone_str,
+        "utc_offset":   utc_offset,
+        "current_time": current_time,
+        "source":       timezone_src,
+        "data_source":  DATA_SOURCE,
+    })
+
+
+# ---------------------------------------------------------------------------
+# Command: bbox
+# ---------------------------------------------------------------------------
+
+def cmd_bbox(args):
+    """Find POIs within a bounding box using the Overpass API."""
+    try:
+        lat1 = float(args.lat1)
+        lon1 = float(args.lon1)
+        lat2 = float(args.lat2)
+        lon2 = float(args.lon2)
+    except ValueError:
+        error_exit("All coordinate arguments must be numeric values.")
+
+    # Normalize: south/west < north/east
+    south = min(lat1, lat2)
+    north = max(lat1, lat2)
+    west  = min(lon1, lon2)
+    east  = max(lon1, lon2)
+
+    category = args.category.lower()
+    if category not in CATEGORY_TAGS:
+        error_exit(
+            f"Unknown category '{category}'. "
+            f"Valid categories: {', '.join(VALID_CATEGORIES)}"
+        )
+
+    limit = int(args.limit)
+    if limit <= 0:
+        error_exit("Limit must be a positive integer.")
+
+    tag_pairs = _tags_for(category)
+    religion = RELIGION_FILTER.get(category)
+    query = build_overpass_bbox(None, None, south, west, north, east,
+                                limit, religion=religion, tag_pairs=tag_pairs)
+
+    raw = overpass_query(query)
+
+    elements = raw.get("elements", [])
+
+    # Use center of bbox as reference for distance sorting
+    center_lat = (south + north) / 2
+    center_lon = (west + east) / 2
+    places = parse_overpass_elements(elements, ref_lat=center_lat,
+                                     ref_lon=center_lon)
+
+    for p in places:
+        p["category"] = category
+
+    print_json({
+        "bounding_box": {
+            "south": south,
+            "west":  west,
+            "north": north,
+            "east":  east,
+        },
+        "category":    category,
+        "count":       len(places),
+        "results":     places,
+        "data_source": DATA_SOURCE,
+    })
+
+
+# ---------------------------------------------------------------------------
+# Command: area
+# ---------------------------------------------------------------------------
+
+def cmd_area(args):
+    """Get bounding box and area info for a named place."""
+    query = " ".join(args.place)
+    raw = nominatim_search(query, limit=1)
+
+    if not raw:
+        error_exit(f"Could not find place: {query}")
+
+    item = raw[0]
+    bb = item.get("boundingbox", [])
+
+    if len(bb) < 4:
+        error_exit(f"No bounding box data available for: {query}")
+
+    min_lat = float(bb[0])
+    max_lat = float(bb[1])
+    min_lon = float(bb[2])
+    max_lon = float(bb[3])
+
+    # Approximate area in km² using the bounding box
+    # Width in km at the average latitude
+    avg_lat = (min_lat + max_lat) / 2
+    height_km = haversine_m(min_lat, min_lon, max_lat, min_lon) / 1000
+    width_km  = haversine_m(avg_lat, min_lon, avg_lat, max_lon) / 1000
+    approx_area_km2 = round(height_km * width_km, 3)
+
+    print_json({
+        "query":        query,
+        "display_name": item.get("display_name", ""),
+        "lat":          float(item["lat"]),
+        "lon":          float(item["lon"]),
+        "type":         item.get("type", ""),
+        "category":     item.get("category", ""),
+        "bounding_box": {
+            "south": min_lat,
+            "north": max_lat,
+            "west":  min_lon,
+            "east":  max_lon,
+        },
+        "dimensions": {
+            "width_km":  round(width_km, 3),
+            "height_km": round(height_km, 3),
+        },
+        "approx_area_km2": approx_area_km2,
+        "osm_type":        item.get("osm_type", ""),
+        "osm_id":          item.get("osm_id", ""),
+        "data_source":     DATA_SOURCE,
+    })
+
+
+# ---------------------------------------------------------------------------
+# CLI setup
+# ---------------------------------------------------------------------------
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="maps_client.py",
+        description=(
+            "CLI maps tool: geocoding, reverse geocoding, POI search, "
+            "routing, directions, timezone, and area lookup. "
+            "Powered by OpenStreetMap, OSRM, Overpass, and TimeAPI.io. "
+            "No API keys required."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  maps_client.py search Times Square\n"
+            "  maps_client.py reverse 40.758 -73.985\n"
+            "  maps_client.py nearby 40.758 -73.985 restaurant --radius 800\n"
+            "  maps_client.py distance New York --to Los Angeles --mode driving\n"
+            "  maps_client.py directions Paris --to Berlin --mode driving\n"
+            "  maps_client.py timezone 48.8566 2.3522\n"
+            "  maps_client.py bbox 40.70 -74.02 40.78 -73.95 restaurant\n"
+            "  maps_client.py area Manhattan"
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True,
+                                 metavar="COMMAND")
+
+    # -- search --
+    p_search = sub.add_parser(
+        "search",
+        help="Geocode a place name to coordinates.",
+        description="Search for a place by name and return coordinates and details.",
+    )
+    p_search.add_argument(
+        "query", nargs="+",
+        help="Place name or address to search.",
+    )
+
+    # -- reverse --
+    p_reverse = sub.add_parser(
+        "reverse",
+        help="Reverse geocode coordinates to an address.",
+        description="Convert latitude/longitude coordinates to a human-readable address.",
+    )
+    p_reverse.add_argument("lat", help="Latitude (decimal degrees).")
+    p_reverse.add_argument("lon", help="Longitude (decimal degrees).")
+
+    # -- nearby --
+    p_nearby = sub.add_parser(
+        "nearby",
+        help="Find nearby places of a given category.",
+        description=(
+            "Find points of interest near a location using the Overpass API.\n"
+            "Provide either LAT/LON, or use --near \"<address>\" to auto-geocode.\n"
+            "Categories can be specified positionally OR repeated via --category\n"
+            "to merge multiple types in one query (e.g. --category bar --category cafe).\n"
+            f"Categories: {', '.join(VALID_CATEGORIES)}"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_nearby.add_argument(
+        "lat", nargs="?", default=None,
+        help="Center latitude (decimal degrees). Omit if using --near.",
+    )
+    p_nearby.add_argument(
+        "lon", nargs="?", default=None,
+        help="Center longitude (decimal degrees). Omit if using --near.",
+    )
+    p_nearby.add_argument(
+        "category", nargs="?", default=None,
+        help="POI category (use --help for full list). Omit if using --category flags.",
+    )
+    p_nearby.add_argument(
+        "--near", nargs="+", metavar="PLACE",
+        help="Address, city, or landmark to search around (geocoded via Nominatim).",
+    )
+    p_nearby.add_argument(
+        "--category", action="append", dest="category_list", default=[],
+        metavar="CAT",
+        help="POI category (repeatable — adds a type to the search).",
+    )
+    p_nearby.add_argument(
+        "--radius", "-r",
+        default=500, type=int, metavar="METRES",
+        help="Search radius in metres (default: 500).",
+    )
+    p_nearby.add_argument(
+        "--limit", "-n",
+        default=10, type=int, metavar="N",
+        help="Maximum number of results (default: 10).",
+    )
+
+    # -- distance --
+    p_dist = sub.add_parser(
+        "distance",
+        help="Calculate road distance and travel time.",
+        description=(
+            "Calculate road distance and estimated travel time between two places.\n"
+            "Example: maps_client.py distance New York --to Los Angeles"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_dist.add_argument(
+        "origin", nargs="+",
+        help="Origin address or place name.",
+    )
+    p_dist.add_argument(
+        "--to", nargs="+", required=True, metavar="DEST",
+        help="Destination address or place name (required).",
+    )
+    p_dist.add_argument(
+        "--mode", "-m",
+        default="driving",
+        choices=list(OSRM_PROFILES.keys()),
+        help="Travel mode (default: driving).",
+    )
+
+    # -- directions --
+    p_dir = sub.add_parser(
+        "directions",
+        help="Get turn-by-turn directions between two places.",
+        description=(
+            "Get step-by-step navigation directions between two places.\n"
+            "Example: maps_client.py directions Paris --to Berlin --mode driving"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_dir.add_argument(
+        "origin", nargs="+",
+        help="Origin address or place name.",
+    )
+    p_dir.add_argument(
+        "--to", nargs="+", required=True, metavar="DEST",
+        help="Destination address or place name (required).",
+    )
+    p_dir.add_argument(
+        "--mode", "-m",
+        default="driving",
+        choices=list(OSRM_PROFILES.keys()),
+        help="Travel mode (default: driving).",
+    )
+
+    # -- timezone --
+    p_tz = sub.add_parser(
+        "timezone",
+        help="Get timezone information for coordinates.",
+        description="Look up timezone and current local time for a lat/lon coordinate.",
+    )
+    p_tz.add_argument("lat", help="Latitude (decimal degrees).")
+    p_tz.add_argument("lon", help="Longitude (decimal degrees).")
+
+    # -- bbox --
+    p_bbox = sub.add_parser(
+        "bbox",
+        help="Find POIs within a bounding box.",
+        description=(
+            "Search for points of interest within a geographic bounding box.\n"
+            "Tip: use the 'area' command to find bounding boxes for named places.\n"
+            f"Categories: {', '.join(VALID_CATEGORIES)}"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_bbox.add_argument("lat1", help="First corner latitude.")
+    p_bbox.add_argument("lon1", help="First corner longitude.")
+    p_bbox.add_argument("lat2", help="Second corner latitude.")
+    p_bbox.add_argument("lon2", help="Second corner longitude.")
+    p_bbox.add_argument("category", help="POI category to search for.")
+    p_bbox.add_argument(
+        "--limit", "-n",
+        default=20, type=int, metavar="N",
+        help="Maximum number of results (default: 20).",
+    )
+
+    # -- area --
+    p_area = sub.add_parser(
+        "area",
+        help="Get bounding box and area info for a named place.",
+        description=(
+            "Look up a place by name and return its bounding box, dimensions, "
+            "and approximate area. Useful as input to the 'bbox' command."
+        ),
+    )
+    p_area.add_argument(
+        "place", nargs="+",
+        help="Place name to look up (e.g., 'Manhattan' or 'downtown Seattle').",
+    )
+
+    return parser
+
+
+def main():
+    parser = build_parser()
+    args   = parser.parse_args()
+
+    dispatch = {
+        "search":     cmd_search,
+        "reverse":    cmd_reverse,
+        "nearby":     cmd_nearby,
+        "distance":   cmd_distance,
+        "directions": cmd_directions,
+        "timezone":   cmd_timezone,
+        "bbox":       cmd_bbox,
+        "area":       cmd_area,
+    }
+
+    handler = dispatch.get(args.command)
+    if handler is None:
+        error_exit(f"Unknown command: {args.command}")
+
+    handler(args)
+
+
+if __name__ == "__main__":
+    main()