| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297 |
- #!/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 sys
- import time
- import urllib.error
- import urllib.parse
- import urllib.request
- # ---------------------------------------------------------------------------
- # Constants
- # ---------------------------------------------------------------------------
- USER_AGENT = "HermesAgent/1.0 (contact: hermes@agent.ai)"
- 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 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:
- 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:
- 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)
- error_exit(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()
|