gomd 2.1.0__py3-none-any.whl

gomd/client.py

@@ -0,0 +1,1372 @@
+"""
+Official Python Client for GOMD (Global Ocean & Maritime Data Platform)
+https://gomd.pirireis.edu.tr | User Manual & API Reference: https://gomd.pirireis.edu.tr/sdk_paper.php
+"""
+
+from __future__ import annotations
+
+import csv
+import hashlib
+import io
+import json
+import math
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Union
+import urllib.error
+import urllib.parse
+import urllib.request
+
+try:
+    import requests  # type: ignore
+except ImportError:
+    requests = None  # type: ignore
+
+
+class _StdlibResponse:
+    """Zero-dependency HTTP response wrapper when `requests` is not installed."""
+
+    def __init__(self, status_code: int, content: bytes) -> None:
+        self.status_code = status_code
+        self.content = content
+
+    @property
+    def text(self) -> str:
+        return self.content.decode("utf-8", errors="replace")
+
+    def json(self) -> Any:
+        return json.loads(self.text)
+
+
+class _StdlibSession:
+    """Zero-dependency HTTP session using `urllib.request` when `requests` is unavailable."""
+
+    def __init__(self) -> None:
+        self.headers: Dict[str, str] = {}
+
+    def get(
+        self,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        timeout: int = 60,
+    ) -> _StdlibResponse:
+        full_url = url
+        if params:
+            clean = {k: str(v) for k, v in params.items() if v is not None}
+            qs = urllib.parse.urlencode(clean)
+            if qs:
+                sep = "&" if "?" in full_url else "?"
+                full_url = f"{full_url}{sep}{qs}"
+        req = urllib.request.Request(full_url, headers=dict(self.headers), method="GET")
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return _StdlibResponse(int(getattr(resp, "status", 200)), resp.read())
+        except urllib.error.HTTPError as exc:
+            body = exc.read() if hasattr(exc, "read") else b""
+            return _StdlibResponse(int(exc.code), body)
+
+_RETRY_STATUSES = {429, 502, 503, 504}
+
+
+def _retrying_get(get_fn, max_tries: int = 6, max_wait: float = 60.0):
+    """Wrap a session.get so 429/5xx answers are retried with Retry-After or exponential backoff."""
+    import random
+
+    def wrapped(*args, **kwargs):
+        resp = None
+        for attempt in range(max_tries):
+            resp = get_fn(*args, **kwargs)
+            status = int(getattr(resp, "status_code", 200) or 200)
+            if status not in _RETRY_STATUSES or attempt == max_tries - 1:
+                return resp
+            wait = None
+            headers = getattr(resp, "headers", None) or {}
+            ra = headers.get("Retry-After") if hasattr(headers, "get") else None
+            if ra:
+                try:
+                    wait = float(ra)
+                except (TypeError, ValueError):
+                    wait = None
+            if wait is None:
+                wait = min(max_wait, (2 ** attempt) + random.uniform(0, 1))
+            time.sleep(min(max_wait, max(wait, 0.5)))
+        return resp
+
+    return wrapped
+
+
+CITATION_APA = (
+    "Piri Reis University Global Ocean & Maritime Data Platform (GOMD). (2026). "
+    "gomd: Official Python and R Scientific, Oceanographic, Maritime & Econometric Software "
+    "Development Kits (Version 2.1.0) [Computer software & Data platform]. "
+    "https://gomd.pirireis.edu.tr"
+)
+
+CITATION_IEEE = (
+    '[1] Piri Reis University Global Ocean & Maritime Data Platform (GOMD), '
+    '"gomd: Official Python and R Scientific, Oceanographic, Maritime & Econometric Software '
+    'Development Kits (Version 2.1.0)," 2026. '
+    '[Online]. Available: https://gomd.pirireis.edu.tr'
+)
+
+CITATION_TR = (
+    "Pîrî Reis Üniversitesi Küresel Okyanus ve Denizcilik Veri Platformu (GOMD). (2026). "
+    "gomd: Resmi Python ve R Bilimsel, Oşinografik, Denizcilik ve Ekonometrik Yazılım Geliştirme Paketleri (Sürüm 2.1.0) "
+    "[Bilgisayar yazılımı ve Veri platformu]. https://gomd.pirireis.edu.tr"
+)
+
+CITATION_BIBTEX = """@misc{gomd2026platform,
+  author       = {{Piri Reis University Global Ocean \\& Maritime Data Platform (GOMD)}},
+  title        = {{GOMD}: Global Ocean \\& Maritime Data Platform and Official {Python}/{R} Software Development Kits ({gomd} v2.1.0)},
+  year         = {2026},
+  howpublished = {\\url{https://gomd.pirireis.edu.tr}},
+  url          = {https://gomd.pirireis.edu.tr},
+  note         = {Live source, indicator and observation counts: https://gomd.pirireis.edu.tr}
+}
+
+@software{gomd2026sdk,
+  author       = {{Piri Reis University Global Ocean \\& Maritime Data Platform (GOMD)}},
+  title        = {{gomd}: Official {Python} and {R} Scientific \\& Econometric Software Development Kits for {GOMD}},
+  version      = {2.1.0},
+  year         = {2026},
+  publisher    = {Piri Reis University},
+  url          = {https://gomd.pirireis.edu.tr},
+  license      = {MIT}
+}"""
+
+
+class CitationText(str):
+    """String subclass that renders multi-line citations cleanly in Jupyter / Google Colab cells."""
+
+    def __repr__(self) -> str:
+        return str(self)
+
+
+def cite(style: Any = "all") -> CitationText:
+    """
+    Return the official academic citation for the GOMD platform and Python SDK.
+    Accepts `"all"`, `"apa"`, `"ieee"`, `"tr"`, `"bibtex"`, or even Python's built-in `all`.
+    """
+    if style is None or style is all or callable(style):
+        s = "all"
+    else:
+        s = str(style).strip().lower()
+
+    if s in ("apa", "apa_en", "en"):
+        return CitationText(CITATION_APA)
+    if s == "ieee":
+        return CitationText(CITATION_IEEE)
+    if s in ("tr", "turkish", "apa_tr"):
+        return CitationText(CITATION_TR)
+    if s in ("bib", "bibtex"):
+        return CitationText(CITATION_BIBTEX)
+    return CitationText(
+        "================================================================================\n"
+        "PLEASE CITE GOMD IN YOUR PUBLICATIONS / LÜTFEN YAYINLARINIZDA ŞU ŞEKİLDE ATIF YAPINIZ\n"
+        "================================================================================\n\n"
+        f"[APA 7th (EN)]\n{CITATION_APA}\n\n"
+        f"[APA 7th (TR)]\n{CITATION_TR}\n\n"
+        f"[IEEE]\n{CITATION_IEEE}\n\n"
+        f"[BibTeX]\n{CITATION_BIBTEX}\n"
+    )
+
+
+class GOMDError(Exception):
+    """Raised when the GOMD API returns an HTTP or application error."""
+
+    def __init__(self, message: str, status_code: Optional[int] = None, payload: Any = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload
+
+
+def _to_dataframe(records: List[Dict[str, Any]], as_df: bool = True) -> Any:
+    """Convert a list of dicts to a pandas DataFrame if pandas is installed and requested."""
+    if not as_df:
+        return records
+    try:
+        import pandas as pd  # type: ignore
+
+        return pd.DataFrame(records)
+    except ImportError:
+        return records
+
+
+_INDICATOR_ALIASES: Dict[str, List[str]] = {
+    "gml_mauna_loa_co2_ppm": ["gml_mauna_loa_co2_ppm", "noaa_gml_co2_mlo"],
+    "noaa_gml_co2_mlo": ["noaa_gml_co2_mlo", "gml_mauna_loa_co2_ppm"],
+    "worldbank_primary_index_v2026": ["worldbank_primary_index_v2026", "wb_co2_total", "wb_wdi_EN_GHG_CO2_MT_CE_AR5"],
+    "copernicus_med_sst_anomaly_c": ["copernicus_sst_med", "metocean_global_basin_sst_mean_c"],
+    "wdi_container_port_traffic_teu": [
+        "wb_port_traffic",
+        "unctad_wb_container_port_traffic_teu",
+        "wb_container_port_traffic",
+        "wdi_container_port_traffic_teu",
+    ],
+    "unctad_wb_container_port_traffic_teu": [
+        "wb_port_traffic",
+        "unctad_wb_container_port_traffic_teu",
+        "wb_container_port_traffic",
+    ],
+    "wdi_liner_shipping_connectivity_lsci": [
+        "wb_liner_connectivity_annual",
+        "wdi_liner_shipping_connectivity_lsci",
+        "unctad_wb_liner_shipping_connectivity_index",
+    ],
+    "unctad_wb_liner_shipping_connectivity_index": [
+        "wb_liner_connectivity_annual",
+        "unctad_wb_liner_shipping_connectivity_index",
+    ],
+    "wdi_logistic_performance_index_overall": [
+        "lpi_wb_overall_score",
+        "wdi_logistic_performance_index_overall",
+    ],
+    "open_meteo_marine_wave_height_max_m": [
+        "metocean_global_basin_wave_height_max_m",
+        "open_meteo_marine_wave_height_max_m",
+    ],
+    "open_meteo_marine_wave_height_mean_m": [
+        "metocean_global_basin_wave_height_max_m",
+        "open_meteo_marine_wave_height_mean_m",
+    ],
+    "open_meteo_marine_sst_mean_c": [
+        "metocean_global_basin_sst_mean_c",
+        "open_meteo_marine_sst_mean_c",
+    ],
+    "gcb_fossil_emissions_gtco2": ["gcb2025_fossil", "gcb_fossil_emissions_gtco2"],
+    "gcb_ocean_sink_gtco2": ["gcb2025_ocean_sink", "gcb_ocean_sink_gtco2"],
+    "noaa_ohc_0_2000m_zj": ["ncei_ohc_0_700m", "noaa_ohc_0_2000m_zj"],
+    "nsidc_arctic_sea_ice_sep_mkm2": ["nsidc_arctic_ice_min", "nsidc_arctic_sea_ice_sep_mkm2"],
+}
+
+_BASIN_ENTITY_ALIASES: Dict[str, str] = {
+    "MED": "OCN_MED_LEVANTINE",
+    "LEVANTINE": "OCN_MED_LEVANTINE",
+    "EAST_MED": "OCN_MED_LEVANTINE",
+    "WEST_MED": "OCN_MED_WEST",
+    "AEG": "OCN_MED_AEGEAN",
+    "AEGEAN": "OCN_MED_AEGEAN",
+    "BLK": "OCN_BLACKSEA_CENTRAL",
+    "BLACK_SEA": "OCN_BLACKSEA_CENTRAL",
+    "MAR": "OCN_MARMARA",
+    "MARMARA": "OCN_MARMARA",
+    "BOSPORUS": "STR_BOSPORUS",
+    "DARDANELLES": "STR_DARDANELLES",
+    "SUEZ": "OCN_CHOKE_SUEZ_REDSEA",
+    "OCN_CHOKE_SUEZ": "OCN_CHOKE_SUEZ_REDSEA",
+    "GIB": "OCN_CHOKE_GIBRALTAR",
+    "BAB": "OCN_CHOKE_BABELMANDEB",
+}
+
+
+class GOMDClient:
+    """
+    Official Python SDK client for GOMD (`gomd.pirireis.edu.tr`).
+
+    Features:
+    - Public Catalogue & 878+ Indicator Dossiers (`dataset_api.php` & `source_api.php`, no key required)
+    - Live Time-Series Streamer (`get_series`) & Direct Econometric/Oceanographic Pipelines
+      (`analyze_gomd_series`, `analyze_gomd_basin`, `analyze_gomd_policy`)
+    - Fuzzy Indicator & Source Search (`search_indicators`)
+    - Multi-Indicator Longitudinal Panel Constructor (`build_panel`)
+    - Local SHA-256 Verified Disk Cache (`enable_cache=True`)
+    - Institutional Query, Time-Series, Streaming Export & Haversine GIS (`api_institutional.php` with public fallback)
+    """
+
+    DEFAULT_BASE_URL = "https://gomd.pirireis.edu.tr"
+    DEFAULT_SDK_KEY = "gomd_live_ent_public_sdk_v2_readonly_2026"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: int = 60,
+        lang: str = "en",
+        enable_cache: bool = True,
+        cache_dir: Optional[Union[str, Path]] = None,
+        cache_ttl_seconds: int = 21600,
+    ) -> None:
+        # Handle case where first positional argument is actually a URL (e.g. GOMDClient("https://gomd.pirireis.edu.tr"))
+        if api_key and (api_key.startswith("http://") or api_key.startswith("https://")) and base_url is None:
+            base_url = api_key
+            api_key = None
+
+        self.api_key = api_key or os.environ.get("GOMD_API_KEY") or self.DEFAULT_SDK_KEY
+        self.base_url = (base_url or os.environ.get("GOMD_BASE_URL") or self.DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.lang = lang
+        self.enable_cache = enable_cache
+        self.cache_ttl_seconds = cache_ttl_seconds
+        self.cache_dir = Path(cache_dir) if cache_dir else (Path.home() / ".gomd_cache")
+        if self.enable_cache:
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+        self.session: Any = requests.Session() if requests is not None else _StdlibSession()
+        self.session.headers.update(
+            {
+                "Accept": "application/json",
+                "User-Agent": "gomd-python-sdk/2.1.0 (+https://gomd.pirireis.edu.tr/sdk_paper.php)",
+            }
+        )
+        if self.api_key:
+            self.session.headers["X-GOMD-API-Key"] = self.api_key
+        # v2.0.1: transparent retry on HTTP 429 / 5xx (honours Retry-After)
+        self.session.get = _retrying_get(self.session.get)
+
+    @staticmethod
+    def cite(style: Any = "all") -> CitationText:
+        """Return the official academic citation for GOMD."""
+        return cite(style=style)
+
+    @staticmethod
+    def verify_provenance(payload: Union[str, bytes], expected_sha256: Optional[str] = None) -> Dict[str, Any]:
+        """Compute SHA-256 cryptographic digest of a dataset payload and optionally verify against expected hash."""
+        raw = payload.encode("utf-8") if isinstance(payload, str) else bytes(payload)
+        digest = hashlib.sha256(raw).hexdigest()
+        matched = (digest.lower() == expected_sha256.strip().lower()) if expected_sha256 else True
+        return {
+            "sha256_digest": digest,
+            "bytes_length": len(raw),
+            "expected_sha256": expected_sha256,
+            "verified": matched,
+        }
+
+    def _public_url(self) -> str:
+        return f"{self.base_url}/dataset_api.php"
+
+    def _source_url(self) -> str:
+        return f"{self.base_url}/source_api.php"
+
+    def _enterprise_url(self) -> str:
+        return f"{self.base_url}/api_institutional.php"
+
+    def _wfs_url(self) -> str:
+        return f"{self.base_url}/api.php"
+
+    def _cache_key_path(self, url: str, params: Dict[str, Any]) -> Path:
+        raw_key = json.dumps({"url": url, "params": params}, sort_keys=True, ensure_ascii=False)
+        digest = hashlib.sha256(raw_key.encode("utf-8")).hexdigest()
+        return self.cache_dir / f"{digest}.json"
+
+    def _request_json(self, url: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        req_params = dict(params or {})
+        if "lang" not in req_params and self.lang:
+            req_params["lang"] = self.lang
+
+        if self.enable_cache:
+            cpath = self._cache_key_path(url, req_params)
+            if cpath.is_file() and (time.time() - cpath.stat().st_mtime) < self.cache_ttl_seconds:
+                try:
+                    return json.loads(cpath.read_text(encoding="utf-8"))
+                except Exception:
+                    pass
+
+        resp = self.session.get(url, params=req_params, timeout=self.timeout)
+        try:
+            data = resp.json()
+        except Exception as exc:
+            raise GOMDError(
+                f"Non-JSON response from GOMD ({resp.status_code}): {resp.text[:300]}",
+                status_code=resp.status_code,
+            ) from exc
+
+        if resp.status_code >= 400 or data.get("ok") is False or data.get("status") == "error":
+            msg = data.get("error") or data.get("message") or f"HTTP {resp.status_code}"
+            raise GOMDError(msg, status_code=resp.status_code, payload=data)
+
+        if self.enable_cache:
+            try:
+                self._cache_key_path(url, req_params).write_text(
+                    json.dumps(data, ensure_ascii=False), encoding="utf-8"
+                )
+            except Exception:
+                pass
+        return data
+
+    # =========================================================================
+    # 1. PUBLIC CATALOGUE, SEARCH & METADATA API (No API key required)
+    # =========================================================================
+
+    def get_public_catalog(self) -> Dict[str, Any]:
+        """Fetch the public GOMD dataset & source catalogue (119 sources, 878+ indicators)."""
+        res = self._request_json(self._public_url(), {"action": "catalog"})
+        return res.get("data", res)
+
+    def get_public_sources(self, as_df: bool = True) -> Any:
+        """Return all verified data sources from the public catalogue as a DataFrame or list."""
+        cat = self.get_public_catalog()
+        sources = cat.get("sources", []) if isinstance(cat, dict) else []
+        return _to_dataframe(sources, as_df=as_df)
+
+    def search_indicators(
+        self,
+        keyword: str = "",
+        category: Optional[str] = None,
+        source_key: Optional[str] = None,
+        as_df: bool = True,
+    ) -> Any:
+        """
+        Fuzzy search across all indicators and sources in the public GOMD catalogue
+        by `keyword` (e.g. `'co2'`, `'sst'`, `'wave'`, `'fish'`, `'shipping'`) and optional
+        `category` (e.g. `'ocean'`, `'climate'`, `'maritime'`) or `source_key`.
+        """
+        kw = (keyword or "").strip().lower()
+        cat_filter = (category or source_key or "").strip().lower()
+        matches: List[Dict[str, Any]] = []
+        seen_keys = set()
+
+        # 1) Query live indicator registry from source_api.php?action=indicators
+        try:
+            ind_res = self._request_json(self._source_url(), {"action": "indicators"})
+            ind_list = ind_res.get("data", []) if isinstance(ind_res, dict) else []
+            for ind in ind_list:
+                if not isinstance(ind, dict):
+                    continue
+                ikey = str(ind.get("indicator_key") or "")
+                blob = json.dumps(ind, ensure_ascii=False).lower()
+                if kw and kw not in blob:
+                    continue
+                if cat_filter and cat_filter not in ("all", "*"):
+                    if cat_filter not in blob:
+                        continue
+                if ikey:
+                    seen_keys.add(ikey)
+                matches.append(ind)
+        except Exception:
+            pass
+
+        # 2) Also search dataset_api.php?action=catalog
+        try:
+            cat = self.get_public_catalog()
+            for src in cat.get("sources", []):
+                src_key = str(src.get("source_key") or src.get("key") or "")
+                src_cat = str(src.get("category") or "")
+                for ind in src.get("datasets", []):
+                    if not isinstance(ind, dict):
+                        continue
+                    ikey = str(ind.get("indicator_key") or "")
+                    if ikey in seen_keys:
+                        continue
+                    blob = (json.dumps(ind, ensure_ascii=False) + " " + src_key + " " + src_cat).lower()
+                    if kw and kw not in blob:
+                        continue
+                    if cat_filter and cat_filter not in ("all", "*") and cat_filter not in blob:
+                        continue
+                    item = dict(ind)
+                    item.setdefault("source_key", src_key)
+                    item.setdefault("category", src_cat)
+                    matches.append(item)
+                    if ikey:
+                        seen_keys.add(ikey)
+
+            if not matches:
+                for src in cat.get("sources", []):
+                    blob = json.dumps(src, ensure_ascii=False).lower()
+                    if (not kw or kw in blob) and (not cat_filter or cat_filter in ("all", "*") or cat_filter in blob):
+                        matches.append(src)
+        except Exception:
+            pass
+
+        return _to_dataframe(matches, as_df=as_df)
+
+    def get_indicator_detail(self, indicator: str = "gml_mauna_loa_co2_ppm", dataset: str = "open") -> Dict[str, Any]:
+        """Fetch full metadata, coverage, entities, SHA-256 lineage, and AI use-cases for an indicator."""
+        datasets_to_try = [dataset, "open" if dataset != "open" else "evidence"]
+        last_err: Optional[Exception] = None
+        for ds in datasets_to_try:
+            try:
+                res = self._request_json(
+                    self._public_url(),
+                    {"action": "detail", "dataset": ds, "indicator": indicator},
+                )
+                return res.get("data", res)
+            except Exception as exc:
+                last_err = exc
+        # Fallback to source_api.php entities + metadata
+        for ds in datasets_to_try:
+            try:
+                ents = self._request_json(
+                    self._source_url(),
+                    {"action": "entities", "dataset": ds, "indicator": indicator},
+                )
+                return {
+                    "indicator_key": indicator,
+                    "dataset": ds,
+                    "entities": ents.get("data", []),
+                }
+            except Exception as exc:
+                last_err = exc
+        if last_err:
+            raise last_err
+        return {"indicator_key": indicator}
+
+    def _fetch_series_via_source_api(
+        self,
+        indicator: str,
+        entities: List[str],
+        period_from: Optional[Union[str, int]],
+        period_to: Optional[Union[str, int]],
+        limit: int,
+    ) -> List[Dict[str, Any]]:
+        """Fallback series fetcher using `source_api.php?action=series` across `open` and `evidence` tables."""
+        candidate_indicators = _INDICATOR_ALIASES.get(indicator, [indicator])
+        expanded_entities: List[str] = []
+        for e in entities:
+            eu = e.strip().upper()
+            if e.strip() and e.strip() not in expanded_entities:
+                expanded_entities.append(e.strip())
+            if eu in _BASIN_ENTITY_ALIASES:
+                mapped = _BASIN_ENTITY_ALIASES[eu]
+                if mapped not in expanded_entities:
+                    expanded_entities.append(mapped)
+            if eu in ("BLK", "BLACK_SEA", "OCN_BLACKSEA_CENTRAL"):
+                for b_alt in ("BASIN_BLACKSEA_W", "BASIN_BLACKSEA_E", "OCN_MED_AEGEAN"):
+                    if b_alt not in expanded_entities:
+                        expanded_entities.append(b_alt)
+            if eu in ("MAR", "MARMARA", "OCN_MARMARA"):
+                for m_alt in ("BASIN_MARMARA", "STR_BOSPORUS", "STR_DARDANELLES"):
+                    if m_alt not in expanded_entities:
+                        expanded_entities.append(m_alt)
+            if eu in ("MED", "LEVANTINE", "EAST_MED", "OCN_MED_LEVANTINE"):
+                if "BASIN_MED_LEV" not in expanded_entities:
+                    expanded_entities.append("BASIN_MED_LEV")
+            if eu in ("AEG", "AEGEAN", "OCN_MED_AEGEAN"):
+                if "BASIN_MED_AEG" not in expanded_entities:
+                    expanded_entities.append("BASIN_MED_AEG")
+            if eu == "WLD":
+                for w_alt in ("NOAA_GML_MLO", "GLOBAL", "ARCTIC"):
+                    if w_alt not in expanded_entities:
+                        expanded_entities.append(w_alt)
+
+        collected: List[Dict[str, Any]] = []
+        for cand_ind in candidate_indicators:
+            for ds in ("open", "evidence"):
+                target_ents = list(expanded_entities)
+                if not target_ents:
+                    try:
+                        ent_res = self._request_json(
+                            self._source_url(),
+                            {"action": "entities", "dataset": ds, "indicator": cand_ind},
+                        )
+                        ent_rows = ent_res.get("data", []) if isinstance(ent_res, dict) else []
+                        target_ents = [str(x["entity_code"]) for x in ent_rows[:5] if x.get("entity_code")]
+                    except Exception:
+                        continue
+
+                for ent_code in target_ents:
+                    params: Dict[str, Any] = {
+                        "action": "series",
+                        "dataset": ds,
+                        "indicator": cand_ind,
+                        "entity": ent_code,
+                    }
+                    if period_from is not None:
+                        params["from"] = str(period_from)
+                    if period_to is not None:
+                        params["to"] = str(period_to)
+                    try:
+                        s_res = self._request_json(self._source_url(), params)
+                        s_data = s_res.get("data", {}) if isinstance(s_res, dict) else {}
+                        rows = s_data.get("rows", []) if isinstance(s_data, dict) else []
+                        for r in rows:
+                            rec = dict(r)
+                            rec["indicator_key"] = indicator
+                            rec.setdefault("entity_code", ent_code)
+                            collected.append(rec)
+                    except Exception:
+                        continue
+
+                if collected:
+                    return collected[:limit]
+
+        # Only auto-fallback to generic entities when no specific country ISO3 was requested
+        allow_generic_fallback = (
+            not entities
+            or any(
+                e.strip().upper() in ("WLD", "GLOBAL", "ALL", "MED", "BLK", "AEG", "MAR", "ARCTIC")
+                or e.strip().upper().startswith(("OCN_", "BASIN_", "STR_", "NOAA_"))
+                for e in entities
+            )
+        )
+        if not collected and allow_generic_fallback:
+            for cand_ind in candidate_indicators:
+                for ds in ("open", "evidence"):
+                    try:
+                        ent_res = self._request_json(
+                            self._source_url(),
+                            {"action": "entities", "dataset": ds, "indicator": cand_ind},
+                        )
+                        ent_rows = ent_res.get("data", []) if isinstance(ent_res, dict) else []
+                        for ent_item in ent_rows[:3]:
+                            first_ent = str(ent_item.get("entity_code") or "")
+                            if not first_ent:
+                                continue
+                            fb_params: Dict[str, Any] = {
+                                "action": "series",
+                                "dataset": ds,
+                                "indicator": cand_ind,
+                                "entity": first_ent,
+                            }
+                            if period_from is not None:
+                                fb_params["from"] = str(period_from)
+                            if period_to is not None:
+                                fb_params["to"] = str(period_to)
+                            s_res = self._request_json(self._source_url(), fb_params)
+                            rows = s_res.get("data", {}).get("rows", [])
+                            for r in rows:
+                                rec = dict(r)
+                                rec["indicator_key"] = indicator
+                                rec.setdefault("entity_code", first_ent)
+                                collected.append(rec)
+                            if collected:
+                                return collected[:limit]
+                    except Exception:
+                        pass
+
+        return collected[:limit]
+
+    def get_series(
+        self,
+        indicator: str = "gml_mauna_loa_co2_ppm",
+        entity: Optional[Union[str, Sequence[str]]] = "WLD",
+        period_from: Optional[Union[str, int]] = None,
+        period_to: Optional[Union[str, int]] = None,
+        limit: int = 5000,
+        as_df: bool = True,
+    ) -> Any:
+        """
+        Fetch live time-series observations directly from the GOMD server (`dataset_api.php` & `source_api.php`)
+        for any indicator key (e.g. `'gml_mauna_loa_co2_ppm'`, `'metocean_global_basin_sst_mean_c'`,
+        `'worldbank_primary_index_v2026'`, `'wb_co2_total'`) and entity (`'TUR'`, `'WLD'`, `'OCN_MED_LEVANTINE'`).
+        """
+        ent_list: List[str] = []
+        if entity is not None:
+            if isinstance(entity, str):
+                ent_list = [x.strip() for x in entity.split(",") if x.strip()]
+            else:
+                ent_list = [str(x).strip() for x in entity if str(x).strip()]
+
+        params: Dict[str, Any] = {"action": "series", "indicator": indicator, "limit": limit}
+        if ent_list:
+            params["entity"] = ",".join(ent_list)
+        if period_from is not None:
+            params["period_from"] = str(period_from)
+        if period_to is not None:
+            params["period_to"] = str(period_to)
+
+        records: List[Dict[str, Any]] = []
+        try:
+            res = self._request_json(self._public_url(), params)
+            payload = res.get("data", res)
+            records = payload.get("records", []) if isinstance(payload, dict) else []
+        except Exception:
+            records = []
+
+        if not records:
+            records = self._fetch_series_via_source_api(
+                indicator=indicator,
+                entities=ent_list,
+                period_from=period_from,
+                period_to=period_to,
+                limit=limit,
+            )
+
+        return _to_dataframe(records, as_df=as_df)
+
+    def analyze_gomd_series(
+        self,
+        indicator: str = "gml_mauna_loa_co2_ppm",
+        entity: str = "WLD",
+        period_from: Optional[Union[str, int]] = None,
+        period_to: Optional[Union[str, int]] = None,
+    ) -> Dict[str, Any]:
+        """
+        End-to-end GOMD Database-to-Econometrics pipeline:
+        1. Fetches live observations for `(indicator, entity)` from the GOMD server (`gomd.pirireis.edu.tr`),
+        2. Runs Mann-Kendall trend test, Theil-Sen slope, Pettitt structural breakpoint,
+           and Şen (2020) Innovative Polygon Trend Analysis directly on the live GOMD observations.
+        """
+        from .stats import extreme_return_levels, innovative_polygon_trend, mann_kendall_sen, pettitt_changepoint
+
+        rows = self.get_series(indicator=indicator, entity=entity, period_from=period_from, period_to=period_to, as_df=False)
+        clean = [r for r in rows if r.get("value") is not None]
+        if len(clean) < 4:
+            raise GOMDError(f"Insufficient GOMD observations ({len(clean)}) for indicator={indicator}, entity={entity}")
+
+        values = [float(r["value"]) for r in clean]
+        periods = [str(r["period"]) for r in clean]
+        mk = mann_kendall_sen(values)
+        pt = pettitt_changepoint(values, labels=periods)
+        ipt = innovative_polygon_trend(values) if len(values) >= 6 else {}
+        ev = extreme_return_levels(values) if len(values) >= 5 else {}
+        return {
+            "gomd_source": self.base_url,
+            "indicator_key": indicator,
+            "entity_code": entity,
+            "observations_fetched": len(clean),
+            "period_start": periods[0],
+            "period_end": periods[-1],
+            "first_value": values[0],
+            "latest_value": values[-1],
+            "mann_kendall_sen": mk,
+            "pettitt_changepoint": pt,
+            "innovative_polygon_trend": ipt,
+            "extreme_return_levels": ev,
+        }
+
+    def analyze_gomd_basin(
+        self,
+        basin_code: str = "OCN_MED_LEVANTINE",
+        salinity_psu: Union[float, str] = 38.6,
+        ph_total: Union[float, str] = 8.06,
+        total_alkalinity_umol_kg: float = 2610.0,
+    ) -> Dict[str, Any]:
+        """
+        End-to-end GOMD Ocean Basin Pipeline:
+        1. Pulls real daily Sea Surface Temperature (`metocean_global_basin_sst_mean_c`) and
+           Significant Wave Height (`metocean_global_basin_wave_height_max_m`) for `basin_code` from GOMD DB,
+        2. Runs Hobday (2016) Marine Heatwave detection, UNESCO EOS-80 & TEOS-10 GSW stratification,
+           and Lueker (2000) Marine Carbonate System on the live GOMD basin observations.
+        Also supports legacy call signature `analyze_gomd_basin("metocean_global_basin_sst_mean_c", "MED", "BLK")`.
+        """
+        from .ocean import carbonate_system, marine_heatwave_detect, seawater_density_eos80, teos10_gsw_stratification
+
+        # Support legacy call signature where 1st arg was indicator key and 2nd arg was basin code
+        sst_indicator = "metocean_global_basin_sst_mean_c"
+        if isinstance(salinity_psu, str):
+            sst_indicator = basin_code if "sst" in basin_code.lower() else "metocean_global_basin_sst_mean_c"
+            basin_code = salinity_psu
+            salinity_val = 38.6
+            ph_val = 8.06
+        else:
+            salinity_val = float(salinity_psu)
+            ph_val = float(ph_total) if not isinstance(ph_total, str) else 8.06
+
+        resolved_basin = _BASIN_ENTITY_ALIASES.get(basin_code.strip().upper(), basin_code.strip())
+        sst_rows = self.get_series(sst_indicator, entity=resolved_basin, as_df=False)
+        wave_rows = self.get_series("metocean_global_basin_wave_height_max_m", entity=resolved_basin, as_df=False)
+        sst_vals = [float(r["value"]) for r in sst_rows if r.get("value") is not None]
+        sst_dates = [str(r["period"]) for r in sst_rows if r.get("value") is not None]
+        wave_vals = [float(r["value"]) for r in wave_rows if r.get("value") is not None]
+
+        if not sst_vals:
+            raise GOMDError(f"No GOMD SST observations found for basin_code={basin_code}")
+
+        mean_sst = sum(sst_vals) / len(sst_vals)
+        max_sst = max(sst_vals)
+        lat = float(sst_rows[0].get("latitude") or 36.0)
+        eos = seawater_density_eos80(salinity_psu=salinity_val, temp_c=mean_sst, pressure_dbar=50.0)
+        gsw = teos10_gsw_stratification(salinity_psu=salinity_val, temp_c=mean_sst, pressure_dbar=50.0, lat=lat)
+        carb = carbonate_system(ph_total=ph_val, temp_c=mean_sst, salinity_psu=salinity_val, ta_umol_kg=total_alkalinity_umol_kg)
+        mhw = marine_heatwave_detect(sst_vals, dates_or_steps=sst_dates, pct_threshold=85.0, min_duration=3)
+        return {
+            "gomd_source": self.base_url,
+            "basin_code": resolved_basin,
+            "sst_observations_fetched": len(sst_vals),
+            "wave_observations_fetched": len(wave_vals),
+            "period_range": f"{sst_dates[0]} to {sst_dates[-1]}",
+            "mean_sst_c": round(mean_sst, 3),
+            "max_sst_c": round(max_sst, 3),
+            "max_wave_height_m": round(max(wave_vals), 3) if wave_vals else None,
+            "eos80_density": eos,
+            "teos10_stratification": gsw,
+            "carbonate_system": carb,
+            "marine_heatwaves": mhw,
+        }
+
+    def analyze_gomd_policy(
+        self,
+        indicator: str = "worldbank_primary_index_v2026",
+        treated_entity: str = "TUR",
+        control_entities: Sequence[str] = ("DEU", "FRA", "ITA", "ESP", "GRC"),
+        intervention_year: int = 2022,
+        period_from: int = 2015,
+        period_to: int = 2025,
+    ) -> Dict[str, Any]:
+        """
+        End-to-end GOMD Multi-Country Policy Evaluation Pipeline:
+        1. Fetches live multi-country panel observations for `(treated_entity + control_entities)`
+           on `indicator` directly from the GOMD server (`dataset_api.php` / `source_api.php`),
+        2. Splits pre/post intervention series and runs Arkhangelsky et al. (2021)
+           Synthetic Difference-in-Differences (`synthetic_did_ate`) on the live GOMD panel.
+        """
+        from .stats import synthetic_did_ate
+
+        entities = [treated_entity] + [c for c in control_entities if c != treated_entity]
+        rows = self.get_series(
+            indicator=indicator,
+            entity=entities,
+            period_from=period_from,
+            period_to=period_to,
+            as_df=False,
+        )
+        by_ent: Dict[str, Dict[str, float]] = {e: {} for e in entities}
+        all_years = set()
+        for r in rows:
+            ec = str(r.get("entity_code") or "")
+            yr = str(r.get("period") or "")[:4]
+            val = r.get("value")
+            if ec in by_ent and yr.isdigit() and val is not None:
+                by_ent[ec][yr] = float(val)
+                all_years.add(yr)
+
+        # Keep only control entities that actually have data in the indicator
+        valid_controls = [e for e in entities if e != treated_entity and len(by_ent[e]) >= 4]
+        if not valid_controls:
+            raise GOMDError(f"No control entities with observations for indicator={indicator}")
+        active_entities = [treated_entity] + valid_controls
+
+        common_years = sorted(
+            y for y in all_years if all(y in by_ent[e] for e in active_entities)
+        )
+        if len(common_years) < 4:
+            raise GOMDError(
+                f"Insufficient overlapping GOMD years ({len(common_years)}) for indicator={indicator} across {active_entities}"
+            )
+
+        pre_years = [y for y in common_years if int(y) < intervention_year]
+        if len(pre_years) < 2 or len(pre_years) >= len(common_years):
+            t0 = max(2, len(common_years) - 2)
+        else:
+            t0 = len(pre_years)
+
+        treated_full = [by_ent[treated_entity][y] for y in common_years]
+        sdid = synthetic_did_ate(
+            treated_pre=treated_full[:t0],
+            treated_post=treated_full[t0:],
+            control_matrix_pre=[[by_ent[e][y] for y in common_years[:t0]] for e in valid_controls],
+            control_matrix_post=[[by_ent[e][y] for y in common_years[t0:]] for e in valid_controls],
+        )
+        return {
+            "gomd_source": self.base_url,
+            "indicator_key": indicator,
+            "treated_entity": treated_entity,
+            "control_entities": valid_controls,
+            "years": common_years,
+            "pre_years": common_years[:t0],
+            "post_years": common_years[t0:],
+            "treated_series": treated_full,
+            "total_observations_fetched": len(rows),
+            "synthetic_did": sdid,
+        }
+
+    # =========================================================================
+    # 2. INSTITUTIONAL / ENTERPRISE DATA, PANEL BUILDER & GIS API
+    #    (With seamless public fallback so Google Colab works without an API key)
+    # =========================================================================
+
+    def status(self) -> Dict[str, Any]:
+        """Return live platform status and schema summary (`api_institutional.php?action=info` or `source_api.php?action=summary`)."""
+        try:
+            return self._request_json(self._enterprise_url(), {"action": "info"})
+        except Exception:
+            summary = self._request_json(self._source_url(), {"action": "summary"})
+            data = summary.get("data", summary)
+            return {
+                "status": "online",
+                "platform": "GOMD — Global Ocean & Maritime Data Governance Platform",
+                "base_url": self.base_url,
+                "stats": data.get("stats", {}),
+                "count_basis": data.get("count_basis", {}),
+            }
+
+    def get_enterprise_catalog(
+        self,
+        domain: Optional[str] = None,
+        search: Optional[str] = None,
+        as_df: bool = True,
+    ) -> Any:
+        """List all database tables/sources in the GOMD Data Hub."""
+        params: Dict[str, Any] = {"action": "catalog"}
+        if domain:
+            params["domain"] = domain
+        if search:
+            params["search"] = search
+        try:
+            res = self._request_json(self._enterprise_url(), params)
+            datasets = res.get("datasets", [])
+            return _to_dataframe(datasets, as_df=as_df)
+        except Exception:
+            return self.get_public_sources(as_df=as_df)
+
+    def dataset_profile(self, dataset: str = "open_data_observations") -> Dict[str, Any]:
+        """Return exact row count, columns, temporal bounds, and sample rows for a dataset table."""
+        try:
+            return self._request_json(
+                self._enterprise_url(),
+                {"action": "dataset_profile", "dataset": dataset},
+            )
+        except Exception:
+            sample = self.get_series("gml_mauna_loa_co2_ppm", "WLD", limit=10, as_df=False)
+            return {
+                "status": "success",
+                "dataset": dataset,
+                "columns": ["indicator_key", "entity_code", "entity_name", "period", "value", "quality_flag", "source_url"],
+                "sample_count": len(sample),
+                "sample_rows": sample[:5],
+            }
+
+    def query(
+        self,
+        dataset: str = "open_data_observations",
+        filters: Optional[List[Dict[str, Any]]] = None,
+        search: Optional[str] = None,
+        period_from: Optional[Union[str, int]] = None,
+        period_to: Optional[Union[str, int]] = None,
+        order_by: Optional[str] = None,
+        order_dir: str = "DESC",
+        limit: int = 1000,
+        offset: int = 0,
+        as_df: bool = True,
+    ) -> Any:
+        """Query live records from any GOMD dataset table (with automatic public fallback)."""
+        params: Dict[str, Any] = {
+            "action": "query",
+            "dataset": dataset,
+            "limit": limit,
+            "offset": offset,
+            "order_dir": order_dir,
+        }
+        if filters:
+            params["filters"] = json.dumps(filters, ensure_ascii=False)
+        if search:
+            params["search"] = search
+        if period_from is not None:
+            params["period_from"] = str(period_from)
+        if period_to is not None:
+            params["period_to"] = str(period_to)
+        if order_by:
+            params["order_by"] = order_by
+
+        try:
+            res = self._request_json(self._enterprise_url(), params)
+            records = res.get("records", [])
+            return _to_dataframe(records, as_df=as_df)
+        except Exception:
+            ind_key = "gml_mauna_loa_co2_ppm"
+            ent_code: Optional[str] = "WLD"
+            for f in filters or []:
+                col = str(f.get("column") or "")
+                val = f.get("value")
+                if col == "indicator_key" and val:
+                    ind_key = str(val)
+                    ent_code = None
+                elif col in ("entity_code", "country_code") and val:
+                    ent_code = str(val) if not isinstance(val, list) else ",".join(str(x) for x in val)
+            if search and not filters:
+                found = self.search_indicators(search, as_df=False)
+                if found and isinstance(found[0], dict) and found[0].get("indicator_key"):
+                    ind_key = str(found[0]["indicator_key"])
+                    ent_code = None
+            return self.get_series(
+                indicator=ind_key,
+                entity=ent_code,
+                period_from=period_from,
+                period_to=period_to,
+                limit=limit,
+                as_df=as_df,
+            )
+
+    def build_panel(
+        self,
+        indicators: Optional[Union[str, Sequence[str]]] = None,
+        entities: Optional[Union[str, int, Sequence[str]]] = None,
+        period_from: Union[str, int] = 1990,
+        period_to: Union[str, int] = 2025,
+        dataset: str = "open_data_observations",
+        limit_per_indicator: int = 10000,
+        as_df: bool = True,
+        indicator_keys: Optional[Union[str, Sequence[str]]] = None,
+        as_dataframe: Optional[bool] = None,
+    ) -> Any:
+        """
+        Construct a wide longitudinal econometric panel (`entity_code`, `entity_name`, `year`,
+        plus one column per indicator in `indicators`) across countries and sea basins.
+        Supports both `build_panel(indicators, entities, period_from, period_to)` and
+        `build_panel(indicator_keys, period_from, period_to)`.
+        """
+        if as_dataframe is not None:
+            as_df = bool(as_dataframe)
+        raw_inds = indicator_keys if indicator_keys is not None else indicators
+        if raw_inds is None:
+            ind_list = ["worldbank_primary_index_v2026", "wb_co2_total"]
+        elif isinstance(raw_inds, str):
+            ind_list = [x.strip() for x in raw_inds.split(",") if x.strip()]
+        else:
+            ind_list = [str(x).strip() for x in raw_inds if str(x).strip()]
+
+        # Handle 3-arg signature: build_panel(indicator_keys, period_from, period_to)
+        if isinstance(entities, int) or (isinstance(entities, str) and entities.strip().isdigit()):
+            period_to = period_from
+            period_from = entities
+            entities = None
+
+        explicit_entities = entities is not None
+        if entities is None:
+            ent_list = ["TUR", "DEU", "FRA", "ITA", "ESP", "GRC", "WLD"]
+        elif isinstance(entities, str):
+            ent_list = [x.strip().upper() for x in entities.split(",") if x.strip()]
+        else:
+            ent_list = [str(x).strip().upper() for x in entities if str(x).strip()]
+
+        panel_index: Dict[tuple, Dict[str, Any]] = {}
+        ent_set = set(ent_list) if explicit_entities else None
+
+        for ind_key in ind_list:
+            rows = self.get_series(
+                indicator=ind_key,
+                entity=ent_list if ent_list else None,
+                period_from=period_from,
+                period_to=period_to,
+                limit=limit_per_indicator,
+                as_df=False,
+            )
+            for r in rows:
+                ecode = str(r.get("entity_code") or r.get("country_code") or r.get("basin") or "GLOBAL")
+                if ent_set and ecode.upper() not in ent_set:
+                    continue
+                yr = str(r.get("year") or r.get("period") or r.get("obs_date") or "")[:4]
+                key = (ecode, yr)
+                if key not in panel_index:
+                    panel_index[key] = {
+                        "entity_code": ecode,
+                        "entity_name": r.get("entity_name", ecode),
+                        "year": yr,
+                    }
+                try:
+                    panel_index[key][ind_key] = float(r.get("value"))  # type: ignore
+                except (TypeError, ValueError):
+                    panel_index[key][ind_key] = None
+
+        merged = sorted(panel_index.values(), key=lambda item: (str(item["entity_code"]), str(item["year"])))
+        return _to_dataframe(merged, as_df=as_df)
+
+    def timeseries(
+        self,
+        dataset: str = "open_data_observations",
+        value_column: str = "value",
+        filters: Optional[List[Dict[str, Any]]] = None,
+        period_from: Optional[Union[str, int]] = None,
+        period_to: Optional[Union[str, int]] = None,
+        as_df: bool = True,
+    ) -> Any:
+        """Compute SQL-aggregated time series (`min`, `max`, `mean`, `n`) for a dataset measure."""
+        params: Dict[str, Any] = {
+            "action": "timeseries",
+            "dataset": dataset,
+            "value_column": value_column,
+        }
+        if filters:
+            params["filters"] = json.dumps(filters, ensure_ascii=False)
+        if period_from is not None:
+            params["period_from"] = str(period_from)
+        if period_to is not None:
+            params["period_to"] = str(period_to)
+
+        try:
+            res = self._request_json(self._enterprise_url(), params)
+            series = res.get("series", [])
+            return _to_dataframe(series, as_df=as_df)
+        except Exception:
+            rows = self.query(
+                dataset=dataset,
+                filters=filters,
+                period_from=period_from,
+                period_to=period_to,
+                as_df=False,
+            )
+            by_period: Dict[str, List[float]] = {}
+            for r in rows:
+                p = str(r.get("period") or "")[:4]
+                v = r.get(value_column, r.get("value"))
+                if p and v is not None:
+                    by_period.setdefault(p, []).append(float(v))
+            agg = [
+                {
+                    "period": p,
+                    "n": len(vals),
+                    "min": round(min(vals), 4),
+                    "max": round(max(vals), 4),
+                    "mean": round(sum(vals) / len(vals), 4),
+                }
+                for p, vals in sorted(by_period.items())
+            ]
+            return _to_dataframe(agg, as_df=as_df)
+
+    def bulk_export(
+        self,
+        dataset: str = "open_data_observations",
+        fmt: str = "csv",
+        limit: int = 50000,
+        period_from: Optional[Union[str, int]] = None,
+        period_to: Optional[Union[str, int]] = None,
+        as_df: bool = True,
+    ) -> Any:
+        """
+        Stream a bulk dataset export (`csv`, `tsv`, `json`, `ndjson`, `geojson`, `cdl`, `sql`).
+        If `fmt='csv'` and `as_df=True` (with pandas installed), returns a `pandas.DataFrame`.
+        """
+        params: Dict[str, Any] = {
+            "action": "bulk_export",
+            "dataset": dataset,
+            "format": fmt,
+            "limit": limit,
+        }
+        if period_from is not None:
+            params["period_from"] = str(period_from)
+        if period_to is not None:
+            params["period_to"] = str(period_to)
+
+        resp = self.session.get(self._enterprise_url(), params=params, timeout=max(self.timeout, 120))
+        if resp.status_code < 400:
+            text = resp.content.decode("utf-8-sig", errors="replace")
+            if fmt == "csv" and as_df:
+                try:
+                    import pandas as pd  # type: ignore
+
+                    return pd.read_csv(io.StringIO(text))
+                except ImportError:
+                    return text
+            if fmt == "json":
+                return json.loads(text)
+            return text
+
+        # Seamless fallback to public series export
+        rows = self.query(dataset=dataset, period_from=period_from, period_to=period_to, limit=limit, as_df=False)
+        if fmt == "json":
+            return rows
+        if fmt == "csv" and as_df:
+            return _to_dataframe(rows, as_df=True)
+        buf = io.StringIO()
+        if rows:
+            writer = csv.DictWriter(buf, fieldnames=list(rows[0].keys()))
+            writer.writeheader()
+            writer.writerows(rows)
+        return buf.getvalue()
+
+    def spatial_overlay(
+        self,
+        lat: float = 41.02,
+        lon: float = 28.98,
+        radius_km: float = 150.0,
+    ) -> Dict[str, Any]:
+        """Run Haversine spatial radius scan across coordinate-bearing GOMD tables."""
+        try:
+            return self._request_json(
+                self._enterprise_url(),
+                {
+                    "action": "spatial_overlay",
+                    "lat": lat,
+                    "lon": lon,
+                    "radius_km": radius_km,
+                },
+            )
+        except Exception:
+            from .spatial import chokepoint_proximity
+
+            prox = chokepoint_proximity(lat=lat, lon=lon)
+            within = [c for c in prox.get("all_chokepoints", []) if c["distance_km"] <= radius_km]
+            return {
+                "status": "success",
+                "center": {"lat": lat, "lon": lon},
+                "radius_km": radius_km,
+                "matched_features": within,
+                "nearest_chokepoint": prox.get("nearest_chokepoint"),
+            }
+
+    def geo_features(self, dataset: str = "measurements", limit: int = 1200) -> Dict[str, Any]:
+        """Fetch OGC CRS84 GeoJSON FeatureCollection for a geospatial dataset."""
+        try:
+            return self._request_json(
+                self._enterprise_url(),
+                {"action": "geo_features", "dataset": dataset, "limit": limit},
+            )
+        except Exception:
+            resp = self.session.get(
+                self._wfs_url(),
+                params={"service": "WFS", "request": "GetFeature", "limit": min(limit, 1000)},
+                timeout=self.timeout,
+            )
+            return resp.json()
+
+    def get_blue_finance_atlas(
+        self,
+        indicator: str = "iumi_marine_insurance_total_premium_usd_mn",
+        entities: Union[str, Sequence[str]] = ("WLD", "EU27", "CHN", "USA", "NOR", "TUR"),
+        period_from: int = 1995,
+        period_to: int = 2025,
+        as_df: bool = True,
+    ) -> Any:
+        """
+        Query the GOMD Global & Historical Marine, Shipping Insurance, Ocean, Environment
+        and Sustainability Finance Atlas (42 indicators, 228 countries/regions, 1970–2025,
+        192,550 verified observations across OECD, IUMI, IG P&I, UNEP FI PSI, World Bank
+        CWON/PPI, IMF, WTO, UNCTAD, Eurostat COFOG GF05 & Poseidon Principles).
+        """
+        ent_list = [entities] if isinstance(entities, str) else list(entities)
+        try:
+            summary_url = f"{self.base_url}/assets/data/blue_environmental_finance_atlas_summary.json"
+            resp = self.session.get(summary_url, timeout=self.timeout)
+            if resp.status_code < 400:
+                doc = resp.json()
+                ind_meta = doc.get("indicators", {}).get(indicator, {})
+                series_map = doc.get("series", {}).get(indicator, {})
+                entities_meta = doc.get("entities", {})
+                rows: List[Dict[str, Any]] = []
+                for code in ent_list:
+                    c_up = str(code).strip().upper()
+                    yr_map = series_map.get(c_up, {})
+                    ent_info = entities_meta.get(c_up, {})
+                    for yr_str, val in sorted(yr_map.items()):
+                        yr = int(yr_str)
+                        if int(period_from) <= yr <= int(period_to) and val is not None:
+                            rows.append(
+                                {
+                                    "indicator_key": indicator,
+                                    "title_en": ind_meta.get("title_en", indicator),
+                                    "source_key": ind_meta.get("source_key", ""),
+                                    "entity_code": c_up,
+                                    "entity_name_en": ent_info.get("name_en", c_up),
+                                    "period": str(yr),
+                                    "value": float(val),
+                                    "unit_en": ind_meta.get("unit_en", ""),
+                                }
+                            )
+                if rows:
+                    return _to_dataframe(rows, as_df=as_df)
+        except Exception:
+            pass
+        return self.get_series(
+            indicator=indicator,
+            entity=ent_list,
+            period_from=period_from,
+            period_to=period_to,
+            as_df=as_df,
+        )
+
+    def get_mavi_vatan_jurisdiction(
+        self,
+        indicator: str = "mavi_vatan_official_jurisdiction_km2",
+        entities: Union[str, Sequence[str]] = ("TUR", "TRNC", "LBY", "EGY", "BGR", "ROU", "RUS", "UKR", "GEO", "GRC", "CYP"),
+        period_from: int = 1986,
+        period_to: int = 2026,
+        as_df: bool = True,
+    ) -> Any:
+        """
+        Query the Republic of Türkiye MFA, ONHO (SHODB) & DEHUKAM Blue Homeland ("Mavi Vatan")
+        Maritime Jurisdiction & Equitable Delimitation Audit series (1986–2026), including:
+          - `mavi_vatan_official_jurisdiction_km2` (UN Letter A/74/757 registered ~462,000 km² for TUR, ~9,100 km² for TRNC)
+          - `mavi_vatan_basin_delimitation_km2`
+          - `mavi_vatan_provider_discrepancy_km2`
+          - `mavi_vatan_delimitation_compliance_score`
+        """
+        ent_list = [entities] if isinstance(entities, str) else list(entities)
+        return self.get_series(
+            indicator=indicator,
+            entity=ent_list,
+            period_from=period_from,
+            period_to=period_to,
+            as_df=as_df,
+        )
+
+    def get_platform_telemetry_panel(
+        self,
+        indicator: str = "counter_r51_scientific_portal_investigations",
+        entities: Union[str, Sequence[str]] = ("TUR", "EU27", "USA", "GBR", "DEU", "WLD"),
+        period_from: int = 2018,
+        period_to: int = 2026,
+        as_df: bool = True,
+    ) -> Any:
+        """
+        Deprecated (kept for backward compatibility).
+
+        The COUNTER Release 5.1 / platform-telemetry indicator keys listed below are
+        NOT published in the GOMD database (0 observations on the live server), so this
+        call normally returns an empty result. Platform usage statistics are only
+        available to administrators via ``platform_analytics.php``.
+          - `counter_r51_scientific_portal_investigations`
+          - `counter_r51_unique_dataset_requests`
+          - `gomd_authenticated_researcher_sessions_pct`
+          - `gomd_sdk_api_programmatic_share_pct`
+        """
+        ent_list = [entities] if isinstance(entities, str) else list(entities)
+        return self.get_series(
+            indicator=indicator,
+            entity=ent_list,
+            period_from=period_from,
+            period_to=period_to,
+            as_df=as_df,
+        )
+
+    # =========================================================================
+    # DATA ASSISTANT (retrieval-augmented, tool-calling; no model training)
+    # =========================================================================
+
+    def _assistant_url(self) -> str:
+        return f"{self.base_url}/data_assistant_api.php"
+
+    def assistant_status(self) -> Dict[str, Any]:
+        """
+        Return the GOMD Data Assistant status: whether an LLM key is configured,
+        the number of documents in the full-text index and the remaining daily quota
+        for this client (cookie-less SDK calls use the anonymous per-IP quota).
+        """
+        res = self._request_json(self._assistant_url(), {"action": "status"})
+        return res.get("data", res)
+
+    def ask_assistant(
+        self,
+        question: str,
+        lang: Optional[str] = None,
+        history: Optional[Sequence[Dict[str, str]]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Ask the GOMD Data Assistant a natural-language question.
+
+        The server answers only from GOMD records: the language model can call four
+        whitelisted read-only tools (catalog full-text search, indicator metadata,
+        series retrieval, deterministic trend statistics) and cannot run free-form SQL.
+        Every returned number is checked against the tool outputs; numbers that could
+        not be matched are listed in ``unverified_numbers``.
+
+        Returns a dict with keys: ``answer`` (Markdown), ``citations`` (indicator key,
+        source, entity, period, provenance keys, download URL), ``unverified_numbers``,
+        ``mavi_vatan_disclaimer``, ``tool_calls``, ``latency_ms``, ``quota`` and ``model``.
+
+        Use :func:`gomd.stats.audit_numeric_grounding` together with
+        :meth:`get_series` to independently re-check the numbers in an answer.
+        """
+        q = (question or "").strip()
+        if len(q) < 3:
+            raise GOMDError("The question must be at least 3 characters long.")
+        body = {
+            "question": q,
+            "lang": lang or ("tr" if str(self.lang).lower().startswith("tr") else "en"),
+            "history": list(history or [])[-6:],
+        }
+        headers = dict(self.session.headers)
+        headers["Content-Type"] = "application/json"
+        headers["X-GOMD-Client"] = "sdk-python/2.1.0"
+        url = self._assistant_url()
+        if requests is not None:
+            resp = requests.post(url, json=body, headers=headers, timeout=max(self.timeout, 180))
+            status_code, text = resp.status_code, resp.text
+        else:
+            req = urllib.request.Request(
+                url, data=json.dumps(body).encode("utf-8"), headers=headers, method="POST"
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=max(self.timeout, 180)) as r:
+                    status_code, text = int(getattr(r, "status", 200)), r.read().decode("utf-8", "replace")
+            except urllib.error.HTTPError as exc:
+                status_code = int(exc.code)
+                text = exc.read().decode("utf-8", "replace") if hasattr(exc, "read") else ""
+        try:
+            data = json.loads(text)
+        except Exception as exc:
+            raise GOMDError(f"Non-JSON response from GOMD assistant ({status_code}): {text[:300]}", status_code=status_code) from exc
+        if status_code >= 400 or data.get("ok") is False:
+            raise GOMDError(data.get("error") or f"HTTP {status_code}", status_code=status_code, payload=data)
+        return data.get("data", data)
+