rsplot 0.2.0__tar.gz → 0.2.2__tar.gz

{rsplot-0.2.0 → rsplot-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rsplot
-Version: 0.2.0
+Version: 0.2.2
 Summary: CLI tool for plotting Remote Sensing data, designed for Agent.
 Project-URL: Repository, https://git.lug.ustc.edu.cn/yaoyhu/rsplot
 Project-URL: GitHub, https://github.com/yaoyhu/rsplot

{rsplot-0.2.0 → rsplot-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rsplot"
-version = "0.2.0"
+version = "0.2.2"
 description = "CLI tool for plotting Remote Sensing data, designed for Agent."
 authors = [
     { name = "Yaoyao Hu", email = "yaoyhu@mail.ustc.edu.cn" },

{rsplot-0.2.0 → rsplot-0.2.2}/src/rsplot/cli.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from importlib.metadata import PackageNotFoundError, version
 import math
 from typing import Any
 
@@ -46,9 +47,27 @@ def _default_raster_n_min(product: str, window_n: int) -> int:
         return max(3, math.ceil(window_n * 0.25))
     return max(3, window_n // 2)
 
+def _get_version() -> str:
+    try:
+        return version("rsplot")
+    except PackageNotFoundError:
+        return "unknown"
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"rsplot {_get_version()}")
+        raise typer.Exit()
 
 @app.callback()
-def _callback() -> None:
+def _callback(
+    show_version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
     "CLI tool for Remote sensing raster plotting."
 
 
@@ -477,6 +496,7 @@ def station(
     console.print(f"[bold]解析区域:[/bold] {region}")
     info = resolve_region(region, cfg, level_override=level)
     console.print(f"  → [green]{info.name}[/green] (级别: {info.level})")
+    params = info.params
 
     # --- 4. Read station data ---
     use_data_dir = (
@@ -850,6 +870,179 @@ def overlay(
     emit_result(result, output)
 
 
+@app.command()
+def recent(
+    region: str = typer.Argument(
+        ..., help="区域名称，如 中国、安徽、合肥、YRD、合肥/蜀山"
+    ),
+    end_date: str = typer.Argument(
+        ..., help="结束日期 YYYYMMDD，最近 N 天统计以该日期为窗口末端"
+    ),
+    days: int = typer.Option(
+        30,
+        "--days",
+        help="最近天数，如 7 / 30 / 365",
+    ),
+    source: str = typer.Option(
+        "raster",
+        "--source",
+        help="数据源: raster / station",
+    ),
+    product: str = typer.Option(
+        "o3",
+        "--product",
+        "-p",
+        help="source=raster 时的产品: no2 / o3 / hcho",
+    ),
+    var: str = typer.Option(
+        "AQI",
+        "--var",
+        "-v",
+        help="source=station 时的变量名: AQI, PM2.5, PM10, NO2, O3, SO2, CO...",
+    ),
+    level: str | None = typer.Option(
+        None,
+        "--level",
+        "-l",
+        help="强制指定级别: country / key_region / province / city / county",
+    ),
+    data_dir: str | None = typer.Option(
+        None,
+        "--data-dir",
+        "-d",
+        help="数据目录 (覆盖配置默认值)",
+    ),
+    output: str | None = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="输出 JSON 路径",
+    ),
+    res: float | None = typer.Option(None, "--res", help="网格分辨率 (度)"),
+    qa: float | None = typer.Option(0.5, "--qa", help="QA 阈值 (0-1)"),
+) -> None:
+    """输出最近 N 天数据 JSON，用于周/月/年变化对比。
+
+    示例:
+        rsplot recent 合肥 20260428 --days 30 -p hcho -o recent.json
+        rsplot recent 安徽 20260428 --days 7 --source station --var O3
+    """
+    from rsplot.config import STATION_VAR_META
+    from rsplot.geo.boundaries import resolve_region
+    from rsplot.readers import get_product_info
+    from rsplot.recent import (
+        build_recent_result,
+        parse_recent_dates,
+        summarize_recent_raster,
+        summarize_recent_station,
+        write_recent_result,
+    )
+
+    use_source = source.lower()
+    if use_source not in ("raster", "station"):
+        console.print("[red]--source 仅支持 raster / station[/red]")
+        raise typer.Exit(1)
+
+    try:
+        dates = parse_recent_dates(end_date, days)
+    except ValueError as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(1) from e
+
+    cfg = AppConfig.load()
+    console.print(f"[bold]解析区域:[/bold] {region}")
+    info = resolve_region(region, cfg, level_override=level)
+    console.print(f"  → [green]{info.name}[/green] (级别: {info.level})")
+    console.print(
+        f"[bold]统计窗口:[/bold] {dates[0]} ~ {dates[-1]} ({len(dates)} 天)"
+    )
+
+    if output is None:
+        if use_source == "raster":
+            output = (
+                f"/tmp/rsplot_recent_{info.name}_{product}_"
+                f"{dates[0]}_{dates[-1]}.json"
+            )
+        else:
+            output = (
+                f"/tmp/rsplot_recent_{info.name}_{var}_"
+                f"{dates[0]}_{dates[-1]}.json"
+            )
+
+    if use_source == "raster":
+        prod_info = get_product_info(product)
+        use_res = res if res is not None else info.params.res
+        use_qa = qa if qa is not None else cfg.qa_threshold
+        use_data_dir = (
+            data_dir if data_dir is not None else cfg.get_data_dir(product)
+        )
+        console.print(
+            f"\n[bold]统计栅格:[/bold] {use_data_dir} "
+            f"(产品: {product}, QA > {use_qa}, res={use_res})"
+        )
+        daily = summarize_recent_raster(
+            region=info,
+            product=product,
+            prod_info=prod_info,
+            data_dir=use_data_dir,
+            dates=dates,
+            res=use_res,
+            qa_threshold=use_qa,
+            console=console,
+        )
+        result = build_recent_result(
+            region=info,
+            source=use_source,
+            dates=dates,
+            daily=daily,
+            params={
+                "data_dir": use_data_dir,
+                "qa_threshold": use_qa,
+                "resolution_deg": use_res,
+            },
+            product=product,
+            unit=prod_info.colorbar_label,
+            output=output,
+        )
+    else:
+        if var not in STATION_VAR_META:
+            available = ", ".join(STATION_VAR_META)
+            console.print(f"[red]未知变量 '{var}'[/red]。可用: {available}")
+            raise typer.Exit(1)
+        use_data_dir = (
+            data_dir if data_dir is not None else cfg.get_data_dir("guokong")
+        )
+        unit = STATION_VAR_META[var][0]
+        console.print(
+            f"\n[bold]统计站点:[/bold] {use_data_dir} (变量: {var})"
+        )
+        daily = summarize_recent_station(
+            region=info,
+            data_dir=use_data_dir,
+            dates=dates,
+            var_name=var,
+            console=console,
+        )
+        result = build_recent_result(
+            region=info,
+            source=use_source,
+            dates=dates,
+            daily=daily,
+            params={"data_dir": use_data_dir},
+            variable=var,
+            unit=unit or None,
+            output=output,
+        )
+
+    write_recent_result(result, output)
+    found = result["availability"]["days_found"]
+    failed = result["availability"]["days_failed"]
+    console.print(
+        f"\n[bold green]✓ 已保存:[/bold green] {output} "
+        f"(有效 {found}/{len(dates)} 天，失败 {failed})"
+    )
+
+
 @app.command()
 def fnr(
     region: str = typer.Argument(

rsplot-0.2.2/src/rsplot/recent.py

@@ -0,0 +1,408 @@
+"""Recent-day JSON summaries for raster and station data.
+
+The ``recent`` command is intentionally read/analysis only: it produces a
+compact JSON payload for comparing the last week/month/year without drawing
+maps. It reuses the existing product readers, gridding, and station filters so
+its daily numbers match the plotting commands' data path.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+from rich.console import Console
+from rich.progress import track
+
+from rsplot.config import STATION_VAR_META, get_exceedance_threshold
+from rsplot.geo.gridding import fill_nan_gaps, grid_data, mask_to_region
+from rsplot.readers import ProductInfo
+from rsplot.readers.guokong import (
+    mask_stations_to_region,
+    read_stations,
+)
+
+if TYPE_CHECKING:
+    from rsplot.geo.boundaries import RegionInfo
+
+
+@dataclass
+class RecentDaily:
+    """One daily summary row."""
+
+    date: str
+    ok: bool
+    value: float | None
+    stats: dict[str, Any]
+    meta: dict[str, Any]
+    error: str | None = None
+
+
+def parse_recent_dates(end_date: str, days: int) -> list[str]:
+    """Return ascending YYYYMMDD dates ending on ``end_date``."""
+    if days < 1:
+        raise ValueError("--days 必须 >= 1")
+    if len(end_date) != 8 or not end_date.isdigit():
+        raise ValueError(f"日期格式错误: '{end_date}'，应为 YYYYMMDD")
+    try:
+        end = datetime.strptime(end_date, "%Y%m%d")
+    except ValueError as e:
+        raise ValueError(
+            f"日期无效: '{end_date}'，请检查年月日是否真实存在 "
+            f"(原始错误: {e})"
+        ) from e
+
+    start = end - timedelta(days=days - 1)
+    return [
+        (start + timedelta(days=i)).strftime("%Y%m%d")
+        for i in range(days)
+    ]
+
+
+def summarize_recent_raster(
+    *,
+    region: "RegionInfo",
+    product: str,
+    prod_info: ProductInfo,
+    data_dir: str,
+    dates: list[str],
+    res: float,
+    qa_threshold: float,
+    console: Console | None = None,
+) -> list[RecentDaily]:
+    """Read daily raster swaths and summarize each day over the region."""
+    if console is None:
+        console = Console()
+
+    reader = prod_info.reader_cls()
+    buf = 1.0
+    read_extent = (
+        region.extent[0] - buf,
+        region.extent[1] + buf,
+        region.extent[2] - buf,
+        region.extent[3] + buf,
+    )
+    out: list[RecentDaily] = []
+
+    for d in track(dates, description=f"[cyan]统计 {product.upper()} 最近数据..."):
+        try:
+            swath = reader.read(data_dir, d, read_extent, qa_threshold)
+            LON, LAT, grid_raw = grid_data(
+                swath.lon, swath.lat, swath.values, read_extent, res
+            )
+            grid = mask_to_region(
+                LON, LAT, fill_nan_gaps(LON, LAT, grid_raw), region.geometry
+            )
+            stats = _grid_stats(grid)
+            if not stats:
+                raise ValueError(f"{d} 区域内无有效网格")
+            out.append(
+                RecentDaily(
+                    date=d,
+                    ok=True,
+                    value=stats.get("mean"),
+                    stats=stats,
+                    meta={
+                        "n_pixels": int(swath.n_pixels),
+                        "n_files": int(swath.n_files),
+                        "n_broken": int(swath.n_broken),
+                    },
+                )
+            )
+        except (FileNotFoundError, ValueError) as e:
+            out.append(
+                RecentDaily(
+                    date=d,
+                    ok=False,
+                    value=None,
+                    stats={},
+                    meta={},
+                    error=str(e).splitlines()[0],
+                )
+            )
+
+    return out
+
+
+def summarize_recent_station(
+    *,
+    region: "RegionInfo",
+    data_dir: str,
+    dates: list[str],
+    var_name: str,
+    console: Console | None = None,
+) -> list[RecentDaily]:
+    """Read daily latest-hour station files and summarize each day."""
+    if console is None:
+        console = Console()
+
+    buf = 0.5
+    read_extent = (
+        region.extent[0] - buf,
+        region.extent[1] + buf,
+        region.extent[2] - buf,
+        region.extent[3] + buf,
+    )
+    threshold = get_exceedance_threshold(var_name)
+    out: list[RecentDaily] = []
+
+    for d in track(dates, description=f"[cyan]统计 {var_name} 站点最近数据..."):
+        try:
+            data, resolved_dt = read_stations(
+                data_dir, d, var_name, extent=read_extent
+            )
+            data = mask_stations_to_region(data, region.geometry)
+            vals = data.values[np.isfinite(data.values)]
+            stats = _array_stats(vals)
+            if not stats:
+                raise ValueError(f"{d} 区域内无有效站点")
+            meta: dict[str, Any] = {
+                "datetime": resolved_dt,
+                "n_stations": int(data.n_stations),
+                "n_valid": int(data.n_valid),
+            }
+            if threshold is not None:
+                meta["threshold"] = threshold
+                meta["n_exceed"] = int((vals > threshold).sum())
+                meta["exceed_rate_pct"] = round(
+                    100 * meta["n_exceed"] / len(vals), 1
+                )
+            out.append(
+                RecentDaily(
+                    date=d,
+                    ok=True,
+                    value=stats.get("mean"),
+                    stats=stats,
+                    meta=meta,
+                )
+            )
+        except (FileNotFoundError, ValueError, KeyError) as e:
+            out.append(
+                RecentDaily(
+                    date=d,
+                    ok=False,
+                    value=None,
+                    stats={},
+                    meta={},
+                    error=str(e).splitlines()[0],
+                )
+            )
+
+    return out
+
+
+def build_recent_result(
+    *,
+    region: "RegionInfo",
+    source: str,
+    dates: list[str],
+    daily: list[RecentDaily],
+    params: dict[str, Any],
+    output: str,
+    product: str | None = None,
+    variable: str | None = None,
+    unit: str | None = None,
+) -> dict[str, Any]:
+    """Build the JSON payload for a recent run."""
+    daily_rows = [_daily_to_json(row) for row in daily]
+    failed = {row.date: row.error for row in daily if not row.ok and row.error}
+    found = [row for row in daily if row.ok]
+
+    result: dict[str, Any] = {
+        "command": "recent",
+        "image": None,
+        "sidecar": output,
+        "source": source,
+        "region": {
+            "name": region.name,
+            "level": region.level,
+            "extent": [round(x, 3) for x in region.extent],
+        },
+        "period": {
+            "start": dates[0],
+            "end": dates[-1],
+            "days_requested": len(dates),
+        },
+        "params": params,
+        "availability": {
+            "days_found": len(found),
+            "days_failed": len(failed),
+            "failed_dates": failed,
+        },
+        "daily": daily_rows,
+        "windows": _window_summaries(daily),
+        "changes": _change_summaries(daily),
+        "trend": _trend_summary(daily),
+        "warnings": _warnings(daily),
+    }
+    if product is not None:
+        result["product"] = product
+    if variable is not None:
+        result["variable"] = variable
+    if unit:
+        result["unit"] = unit
+    return result
+
+
+def write_recent_result(result: dict[str, Any], output: str) -> str:
+    """Write a recent JSON result and return the path."""
+    path = Path(output)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(result, f, ensure_ascii=False, indent=2)
+    return str(path)
+
+
+def _daily_to_json(row: RecentDaily) -> dict[str, Any]:
+    data: dict[str, Any] = {
+        "date": row.date,
+        "ok": row.ok,
+        "stats": row.stats,
+        "meta": row.meta,
+    }
+    if row.error:
+        data["error"] = row.error
+    return data
+
+
+def _window_summaries(daily: list[RecentDaily]) -> dict[str, dict[str, Any]]:
+    windows: dict[str, dict[str, Any]] = {}
+    n = len(daily)
+    specs = [
+        ("last_7", max(0, n - 7), n),
+        ("prev_7", max(0, n - 14), max(0, n - 7)),
+        ("last_30", max(0, n - 30), n),
+        ("prev_30", max(0, n - 60), max(0, n - 30)),
+        ("last_365", max(0, n - 365), n),
+    ]
+    for name, start, end in specs:
+        if end <= start or end - start < _required_span(name):
+            continue
+        windows[name] = _summarize_rows(daily[start:end])
+    return windows
+
+
+def _change_summaries(daily: list[RecentDaily]) -> dict[str, dict[str, Any]]:
+    windows = _window_summaries(daily)
+    pairs = [
+        ("last_7_vs_prev_7", "last_7", "prev_7"),
+        ("last_30_vs_prev_30", "last_30", "prev_30"),
+    ]
+    out: dict[str, dict[str, Any]] = {}
+    for name, cur_key, prev_key in pairs:
+        cur = windows.get(cur_key, {})
+        prev = windows.get(prev_key, {})
+        cur_mean = cur.get("mean")
+        prev_mean = prev.get("mean")
+        if cur_mean is None or prev_mean is None:
+            continue
+        abs_change = round(float(cur_mean) - float(prev_mean), 3)
+        pct_change = None
+        if prev_mean != 0:
+            pct_change = round(100 * abs_change / float(prev_mean), 1)
+        out[name] = {
+            "current_mean": cur_mean,
+            "previous_mean": prev_mean,
+            "abs_change": abs_change,
+            "pct_change": pct_change,
+            "direction": _direction(abs_change),
+            "current_valid_days": cur.get("valid_days", 0),
+            "previous_valid_days": prev.get("valid_days", 0),
+        }
+    return out
+
+
+def _trend_summary(daily: list[RecentDaily]) -> dict[str, Any]:
+    xs = []
+    ys = []
+    for i, row in enumerate(daily):
+        if row.ok and row.value is not None and np.isfinite(row.value):
+            xs.append(i)
+            ys.append(float(row.value))
+    if len(ys) < 2:
+        return {"valid_days": len(ys), "slope_per_day": None, "direction": "flat"}
+    slope = float(np.polyfit(np.asarray(xs, dtype=float), np.asarray(ys), 1)[0])
+    return {
+        "valid_days": len(ys),
+        "slope_per_day": round(slope, 4),
+        "direction": _direction(slope),
+    }
+
+
+def _warnings(daily: list[RecentDaily]) -> list[str]:
+    if not daily:
+        return []
+    valid_days = sum(1 for row in daily if row.ok)
+    rate = valid_days / len(daily)
+    warnings: list[str] = []
+    if valid_days == 0:
+        warnings.append("请求窗口内无有效日期。")
+    elif rate < 0.5:
+        warnings.append("有效日期少于请求天数的一半，变化判断可信度较低。")
+    return warnings
+
+
+def _summarize_rows(rows: list[RecentDaily]) -> dict[str, Any]:
+    values = np.asarray(
+        [row.value for row in rows if row.ok and row.value is not None],
+        dtype=float,
+    )
+    stats = _array_stats(values)
+    stats["valid_days"] = int(len(values))
+    stats["requested_days"] = int(len(rows))
+    return stats
+
+
+def _grid_stats(grid: np.ndarray) -> dict[str, Any]:
+    total = int(grid.size)
+    stats = _array_stats(grid[np.isfinite(grid)])
+    if stats:
+        stats["coverage_pct"] = round(100 * stats["n"] / total, 1)
+        stats["grid_shape"] = list(grid.shape)
+    return stats
+
+
+def _array_stats(values: np.ndarray) -> dict[str, Any]:
+    finite = np.asarray(values, dtype=float)
+    finite = finite[np.isfinite(finite)]
+    if len(finite) == 0:
+        return {}
+    return {
+        "n": int(len(finite)),
+        "min": _round(np.min(finite)),
+        "max": _round(np.max(finite)),
+        "mean": _round(np.mean(finite)),
+        "median": _round(np.median(finite)),
+        "p10": _round(np.percentile(finite, 10)),
+        "p25": _round(np.percentile(finite, 25)),
+        "p75": _round(np.percentile(finite, 75)),
+        "p90": _round(np.percentile(finite, 90)),
+    }
+
+
+def _round(value: float, ndigits: int = 2) -> float | None:
+    if not np.isfinite(value):
+        return None
+    return round(float(value), ndigits)
+
+
+def _direction(delta: float) -> str:
+    if delta > 0:
+        return "up"
+    if delta < 0:
+        return "down"
+    return "flat"
+
+
+def _required_span(name: str) -> int:
+    if name.endswith("_7"):
+        return 7
+    if name.endswith("_30"):
+        return 30
+    if name.endswith("_365"):
+        return 365
+    return 1

{rsplot-0.2.0 → rsplot-0.2.2}/src/rsplot/results.py

@@ -187,21 +187,31 @@ def _attribute_stations_to_cities(
     lon: np.ndarray, lat: np.ndarray, cities_gdf: gpd.GeoDataFrame
 ) -> np.ndarray:
     """Return city name for each (lon, lat); empty string if none contain it."""
+    return _attribute_stations_to_areas(lon, lat, cities_gdf)
+
+
+def _attribute_stations_to_areas(
+    lon: np.ndarray,
+    lat: np.ndarray,
+    areas_gdf: gpd.GeoDataFrame,
+    name_field: str = "name",
+) -> np.ndarray:
+    """Return containing admin-unit name for each (lon, lat)."""
     from shapely.geometry import Point
 
-    sindex = cities_gdf.sindex
+    sindex = areas_gdf.sindex
     out = np.empty(len(lon), dtype=object)
     for i, (x, y) in enumerate(zip(lon, lat)):
         if not (np.isfinite(x) and np.isfinite(y)):
             out[i] = ""
             continue
         pt = Point(float(x), float(y))
-        city = ""
+        area = ""
         for idx in sindex.intersection((x, y, x, y)):
-            if cities_gdf.iloc[idx].geometry.contains(pt):
-                city = cities_gdf.iloc[idx]["name"]
+            if areas_gdf.iloc[idx].geometry.contains(pt):
+                area = areas_gdf.iloc[idx][name_field]
                 break
-        out[i] = city
+        out[i] = area
     return out
 
 
@@ -220,6 +230,46 @@ def _aqi_distribution(vals: np.ndarray) -> dict[str, int]:
     return dist
 
 
+def _station_admin_level(region: RegionInfo) -> str | None:
+    if region.level == "country":
+        return "province"
+    if region.level == "key_region":
+        return "city"
+    if region.level == "province":
+        municipalities = {"北京市", "天津市", "上海市", "重庆市"}
+        return "county" if region.name in municipalities else "city"
+    if region.level == "city":
+        return "county"
+    return None
+
+
+def _top_station_entries(
+    *,
+    vals: np.ndarray,
+    ids: np.ndarray,
+    lons: np.ndarray,
+    lats: np.ndarray,
+    area_names: np.ndarray | None,
+    admin_level: str | None,
+    limit: int = 10,
+) -> list[dict[str, Any]]:
+    top_stations: list[dict[str, Any]] = []
+    for i in np.argsort(vals)[::-1][:limit]:
+        entry: dict[str, Any] = {
+            "id": str(ids[i]),
+            "value": _round(vals[i]),
+            "lon": round(float(lons[i]), 3),
+            "lat": round(float(lats[i]), 3),
+        }
+        if area_names is not None:
+            entry["admin_level"] = admin_level
+            entry["admin_name"] = area_names[i] or None
+            # Backward-compatible alias for older consumers.
+            entry["city"] = area_names[i] or None
+        top_stations.append(entry)
+    return top_stations
+
+
 def build_station_result(
     *,
     region: RegionInfo,
@@ -235,6 +285,12 @@ def build_station_result(
     lons = data.lon[valid]
     lats = data.lat[valid]
     ids = np.asarray(data.id)[valid]
+    admin_gdf = (
+        region.sub_boundary_gdf
+        if region.sub_boundary_gdf is not None and len(region.sub_boundary_gdf) > 0
+        else cities_gdf
+    )
+    admin_level = _station_admin_level(region)
 
     result: dict[str, Any] = {
         "command": "station",
@@ -253,9 +309,25 @@ def build_station_result(
         "stats": _basic_stats(vals),
     }
 
-    station_cities = None
-    if cities_gdf is not None and len(cities_gdf) > 0 and len(vals) > 0:
-        station_cities = _attribute_stations_to_cities(lons, lats, cities_gdf)
+    station_areas = None
+    if admin_gdf is not None and len(admin_gdf) > 0 and len(vals) > 0:
+        station_areas = _attribute_stations_to_areas(
+            lons, lats, admin_gdf, region.sub_name_field
+        )
+
+    if len(vals) > 0:
+        result["top_stations"] = _top_station_entries(
+            vals=vals,
+            ids=ids,
+            lons=lons,
+            lats=lats,
+            area_names=station_areas,
+            admin_level=admin_level,
+            limit=10,
+        )
+        result["top_station_ids"] = [
+            entry["id"] for entry in result["top_stations"]
+        ]
 
     # Exceedance summary
     if threshold is not None and len(vals) > 0:
@@ -272,8 +344,11 @@ def build_station_result(
                 "lon": round(float(lons[i]), 3),
                 "lat": round(float(lats[i]), 3),
             }
-            if station_cities is not None:
-                entry["city"] = station_cities[i] or None
+            if station_areas is not None:
+                entry["admin_level"] = admin_level
+                entry["admin_name"] = station_areas[i] or None
+                # Backward-compatible alias for older consumers.
+                entry["city"] = station_areas[i] or None
             top_stations.append(entry)
             if len(top_stations) >= 10:
                 break
@@ -287,11 +362,11 @@ def build_station_result(
     if data.var_name == "AQI" and len(vals) > 0:
         result["aqi_distribution"] = _aqi_distribution(vals)
 
-    # Per-city ranking
-    if station_cities is not None and len(vals) > 0:
+    # Per-admin-unit ranking, exposed under the legacy city_ranking key.
+    if station_areas is not None and len(vals) > 0:
         acc: dict[str, dict[str, Any]] = {}
         for i in range(len(vals)):
-            c = station_cities[i]
+            c = station_areas[i]
             if not c:
                 continue
             s = acc.setdefault(c, {"values": [], "n_exceed": 0})
@@ -303,6 +378,9 @@ def build_station_result(
             arr = np.asarray(s["values"])
             ranking.append(
                 {
+                    "name": city,
+                    "admin_level": admin_level,
+                    # Backward-compatible alias for older consumers.
                     "city": city,
                     "n_valid": len(arr),
                     "mean": _round(np.mean(arr)),