clouds-everywhere 0.1.0__py3-none-any.whl

clouds_everywhere/__init__.py

@@ -0,0 +1,18 @@
+"""Clouds-Everywhere — check satellite imagery availability by cloud cover."""
+
+from .search import search_images
+from .coverage import check_coverage
+from .query import query
+from .models import (
+    SatelliteImage, TileResult, DateCoverage,
+    TilePeriodStat, PeriodCoverage, QueryReport,
+)
+from .aoi import to_bbox
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "query", "search_images", "check_coverage", "to_bbox",
+    "SatelliteImage", "TileResult", "DateCoverage",
+    "TilePeriodStat", "PeriodCoverage", "QueryReport",
+]

clouds_everywhere/aoi.py

@@ -0,0 +1,161 @@
+"""
+aoi.py — normalize any AOI input to a WGS84 bbox [minX, minY, maxX, maxY].
+
+Accepted inputs
+---------------
+* Plain bbox list/tuple  : [minX, minY, maxX, maxY]
+* Polygon coords         : [[lon, lat], ...]  or  shapely Polygon
+* GeoJSON dict           : FeatureCollection, Feature, or geometry
+* File path (str/Path)   : .geojson, .json, .shp, .zip (zipped shapefile)
+
+Every spatial input is reprojected to WGS84 (EPSG:4326) before the bbox is
+returned, so callers never need to think about CRS.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import geopandas as gpd
+import pyproj
+from shapely.geometry import shape, Polygon
+from shapely.ops import transform, unary_union
+
+
+WGS84 = pyproj.CRS("EPSG:4326")
+
+
+# ── public entry point ────────────────────────────────────────────────────────
+
+def to_bbox(aoi) -> list[float]:
+    """Return [minX, minY, maxX, maxY] in WGS84 for any supported AOI input."""
+    geom, crs = _parse(aoi)
+    geom = _ensure_wgs84(geom, crs)
+    _validate_wgs84_bbox(geom.bounds)
+    minx, miny, maxx, maxy = geom.bounds
+    return [minx, miny, maxx, maxy]
+
+
+# ── parsers — all return (shapely_geom, pyproj.CRS | None) ───────────────────
+
+def _parse(aoi):
+    # shapely geometry passed directly — assume WGS84
+    if hasattr(aoi, "geom_type"):
+        return aoi, None
+
+    # file path
+    if isinstance(aoi, (str, Path)):
+        return _from_file(Path(aoi))
+
+    # empty containers are never a valid AOI
+    if isinstance(aoi, (list, tuple)) and len(aoi) == 0:
+        raise ValueError("AOI is empty - provide a bbox, polygon coords, or GeoJSON")
+
+    # plain bbox [minX, minY, maxX, maxY]
+    if (isinstance(aoi, (list, tuple))
+            and len(aoi) == 4
+            and all(isinstance(v, (int, float)) for v in aoi)):
+        return _bbox_to_polygon(aoi), None
+
+    # polygon as list of coordinate pairs [[x, y], ...]
+    if (isinstance(aoi, (list, tuple))
+            and all(isinstance(v, (list, tuple)) and len(v) == 2 for v in aoi)):
+        if len(aoi) < 3:
+            raise ValueError(
+                f"Polygon needs at least 3 coordinate pairs, got {len(aoi)}"
+            )
+        return _coords_to_polygon(aoi), None
+
+    # GeoJSON dict
+    if isinstance(aoi, dict):
+        return _from_geojson(aoi)
+
+    raise TypeError(f"Unsupported AOI type: {type(aoi)}")
+
+
+def _from_file(path: Path):
+    suffix = path.suffix.lower()
+
+    if suffix in (".geojson", ".json"):
+        gdf = gpd.read_file(path)
+    elif suffix == ".shp":
+        gdf = gpd.read_file(path)
+    elif suffix == ".zip":
+        gdf = gpd.read_file(f"zip://{path}")
+    else:
+        raise ValueError(f"Unsupported file format: {suffix!r}. Use .geojson, .json, .shp, or .zip")
+
+    geom = unary_union(gdf.geometry)
+    crs = gdf.crs  # pyproj.CRS or None
+    return geom, crs
+
+
+def _from_geojson(d: dict):
+    typ = d.get("type")
+
+    if typ == "FeatureCollection":
+        geoms = [shape(f["geometry"]) for f in d["features"] if f.get("geometry")]
+        geom = unary_union(geoms)
+    elif typ == "Feature":
+        geom = shape(d["geometry"])
+    elif typ in ("Polygon", "MultiPolygon", "Point", "LineString",
+                 "MultiPoint", "MultiLineString", "GeometryCollection"):
+        geom = shape(d)
+    else:
+        raise ValueError(f"Unrecognised GeoJSON type: {typ!r}")
+
+    # Some tools embed a CRS object (older GeoJSON / ArcGIS exports)
+    crs = None
+    crs_obj = d.get("crs")
+    if crs_obj:
+        epsg_name = crs_obj.get("properties", {}).get("name", "")
+        try:
+            crs = pyproj.CRS.from_user_input(epsg_name)
+        except Exception:
+            pass  # can't parse it; fall back to WGS84 assumption
+
+    return geom, crs
+
+
+def _bbox_to_polygon(bbox) -> Polygon:
+    minx, miny, maxx, maxy = bbox
+    return Polygon([
+        (minx, miny), (maxx, miny),
+        (maxx, maxy), (minx, maxy),
+        (minx, miny),
+    ])
+
+
+def _coords_to_polygon(coords) -> Polygon:
+    """Accept [[lon, lat], ...] or [[lat, lon], ...] and fix axis order."""
+    coords = [tuple(c) for c in coords]
+
+    xs = [c[0] for c in coords]
+    ys = [c[1] for c in coords]
+
+    # If xs fit in [-90, 90] but ys don't → coords are (lat, lon), swap them
+    if all(-90 <= v <= 90 for v in xs) and any(abs(v) > 90 for v in ys):
+        coords = [(y, x) for x, y in coords]
+
+    return Polygon(coords)
+
+
+# ── CRS reprojection ──────────────────────────────────────────────────────────
+
+def _ensure_wgs84(geom, crs):
+    if crs is None or crs.equals(WGS84):
+        return geom
+    transformer = pyproj.Transformer.from_crs(crs, WGS84, always_xy=True)
+    return transform(transformer.transform, geom)
+
+
+def _validate_wgs84_bbox(bounds):
+    minx, miny, maxx, maxy = bounds
+    if any(v != v for v in bounds):        # NaN check (NaN != NaN)
+        raise ValueError("AOI produced an empty or invalid geometry")
+    if not (-180 <= minx <= 180 and -180 <= maxx <= 180):
+        raise ValueError(f"Longitude out of WGS84 range: minX={minx}, maxX={maxx}")
+    if not (-90 <= miny <= 90 and -90 <= maxy <= 90):
+        raise ValueError(f"Latitude out of WGS84 range: minY={miny}, maxY={maxy}")
+    if minx >= maxx or miny >= maxy:
+        raise ValueError(f"Degenerate bbox (min >= max): {list(bounds)}")

clouds_everywhere/coverage.py

@@ -0,0 +1,89 @@
+from collections import defaultdict
+
+from .providers import sentinel2, landsat
+from .models import DateCoverage
+from .aoi import to_bbox
+
+
+def check_coverage(aoi, start_date, end_date, max_cloud=20, satellites=("sentinel2", "landsat")):
+    """
+    For each date in the range, determine whether all tiles covering the bbox
+    are available and below the cloud threshold.
+
+    Returns a list of DateCoverage objects sorted by date, each flagged as:
+      "full"    — every required tile passes the cloud threshold
+      "partial" — some tiles pass, some are missing or too cloudy
+      "missing" — no tiles pass at all for that date
+    """
+    bbox = to_bbox(aoi)
+
+    fetchers = []
+    if "sentinel2" in satellites:
+        fetchers.append(("sentinel2", sentinel2.search_tiles))
+    if "landsat" in satellites:
+        fetchers.append(("landsat", landsat.search_tiles))
+
+    # One satellite failing (API down, no passes) must not abort coverage.
+    all_tile_results = []
+    for name, fetch in fetchers:
+        try:
+            all_tile_results += fetch(bbox, start_date, end_date)
+        except Exception as e:
+            print(f"[coverage] '{name}' unavailable for this request — skipping ({e})")
+
+    if not all_tile_results:
+        return []
+
+    # Analyse each satellite independently so Sentinel-2 and Landsat tile
+    # grids don't interfere with each other.
+    by_satellite = defaultdict(list)
+    for tr in all_tile_results:
+        by_satellite[tr.satellite].append(tr)
+
+    coverage_results = []
+
+    for satellite, tile_results in by_satellite.items():
+        required_tiles = set(tr.tile_id for tr in tile_results)
+
+        by_date = defaultdict(list)
+        for tr in tile_results:
+            by_date[tr.date].append(tr)
+
+        for date, date_tiles in sorted(by_date.items()):
+            tile_cloud = {tr.tile_id: tr.cloud_cover for tr in date_tiles}
+
+            covered = {
+                t: c for t, c in tile_cloud.items()
+                if c == -1 or c <= max_cloud          # -1 = cloud unknown, include it
+            }
+            failed  = {
+                t: c for t, c in tile_cloud.items()
+                if c != -1 and c > max_cloud
+            }
+            absent  = required_tiles - set(tile_cloud.keys())
+
+            covered_tiles = sorted(covered.keys())
+            missing_tiles = sorted(failed.keys()) + sorted(absent)
+
+            if not missing_tiles:
+                status = "full"
+            elif covered_tiles:
+                status = "partial"
+            else:
+                status = "missing"
+
+            valid_clouds = [c for c in covered.values() if c != -1]
+            avg_cloud = sum(valid_clouds) / len(valid_clouds) if valid_clouds else -1
+
+            coverage_results.append(DateCoverage(
+                date           = date,
+                satellite      = satellite,
+                status         = status,
+                required_tiles = sorted(required_tiles),
+                covered_tiles  = covered_tiles,
+                missing_tiles  = missing_tiles,
+                avg_cloud      = avg_cloud,
+                tile_details   = date_tiles,
+            ))
+
+    return sorted(coverage_results, key=lambda x: (x.date, x.satellite))

clouds_everywhere/models.py

@@ -0,0 +1,224 @@
+from dataclasses import dataclass, field
+from typing import List, Dict
+
+@dataclass
+class SatelliteImage:
+    id: str
+    date: str
+    cloud_cover: float
+    satellite: str
+    thumbnail_url: str
+
+    def __repr__(self):
+        return f"{self.date} | {self.satellite} | Cloud: {self.cloud_cover}%"
+
+
+@dataclass
+class TileResult:
+    tile_id: str
+    date: str
+    cloud_cover: float        # -1 means unknown
+    satellite: str
+    item_id: str
+    thumbnail_url: str
+    geometry: dict | None = None      # GeoJSON geometry from the STAC item
+
+    def __repr__(self):
+        cloud = f"{self.cloud_cover:.1f}%" if self.cloud_cover != -1 else "N/A"
+        return f"{self.date} | {self.satellite} | Tile {self.tile_id} | Cloud: {cloud}"
+
+
+@dataclass
+class DateCoverage:
+    date: str
+    satellite: str
+    status: str                          # "full" | "partial" | "missing"
+    required_tiles: List[str]
+    covered_tiles: List[str]             # tiles that pass the cloud threshold
+    missing_tiles: List[str]             # absent or too cloudy
+    avg_cloud: float                     # average over covered_tiles; -1 if unknown
+    tile_details: List[TileResult] = field(default_factory=list)
+
+    def __repr__(self):
+        cloud = f"{self.avg_cloud:.1f}%" if self.avg_cloud != -1 else "N/A"
+        return (
+            f"{self.date} | {self.satellite} | {self.status.upper()} "
+            f"({len(self.covered_tiles)}/{len(self.required_tiles)} tiles) "
+            f"avg cloud: {cloud}"
+        )
+
+
+# ── Period-based availability report ──────────────────────────────────────────
+
+@dataclass
+class TilePeriodStat:
+    """How much usable imagery exists for a single tile within one time period."""
+    tile_id: str
+    usable_images: int          # scenes at or below the cloud threshold
+    total_images: int           # all scenes acquired, regardless of cloud
+    best_cloud: float           # lowest cloud % seen; -1 if none acquired
+
+    @property
+    def covered(self) -> bool:
+        return self.usable_images > 0
+
+    def __repr__(self):
+        best = f"{self.best_cloud:.1f}%" if self.best_cloud != -1 else "N/A"
+        return f"{self.tile_id}: {self.usable_images} usable / {self.total_images} total (best {best})"
+
+
+@dataclass
+class PeriodCoverage:
+    """Availability of one satellite over the AOI for one time period (day/week/month)."""
+    label: str                  # friendly label, e.g. "13-19 Jan 2024"
+    period_start: str           # "YYYY-MM-DD"
+    period_end: str             # "YYYY-MM-DD"
+    satellite: str
+    status: str                 # "available" | "gap" | "missing"
+    required_tiles: List[str]
+    covered_tiles: List[str]    # tiles with >=1 usable image this period
+    missing_tiles: List[str]    # tiles with zero usable images (the holes)
+    tile_stats: List[TilePeriodStat] = field(default_factory=list)
+
+    @property
+    def n_required(self) -> int:
+        return len(self.required_tiles)
+
+    @property
+    def n_covered(self) -> int:
+        return len(self.covered_tiles)
+
+    @property
+    def total_usable_images(self) -> int:
+        return sum(t.usable_images for t in self.tile_stats)
+
+    def __repr__(self):
+        return (
+            f"{self.label} | {self.satellite} | {self.status.upper()} "
+            f"({self.n_covered}/{self.n_required} tiles, {self.total_usable_images} images)"
+        )
+
+
+@dataclass
+class QueryReport:
+    """
+    Full result of a user query, grouped by time period.
+
+    Use ``print(report)`` or ``report.summary()`` for a friendly, plain-language
+    breakdown, or ``report.to_dataframe()`` for a tabular view.
+    """
+    aoi_bbox: List[float]
+    start_date: str
+    end_date: str
+    max_cloud: float
+    group_by: str                       # "day" | "week" | "month"
+    satellites: List[str]
+    periods: List[PeriodCoverage] = field(default_factory=list)
+
+    # ── convenience views ────────────────────────────────────────────────────
+    def by_satellite(self) -> Dict[str, List[PeriodCoverage]]:
+        out: Dict[str, List[PeriodCoverage]] = {}
+        for p in self.periods:
+            out.setdefault(p.satellite, []).append(p)
+        return out
+
+    def available_periods(self, satellite=None) -> List[PeriodCoverage]:
+        return [p for p in self.periods
+                if p.status == "available" and (satellite is None or p.satellite == satellite)]
+
+    def gap_periods(self, satellite=None) -> List[PeriodCoverage]:
+        return [p for p in self.periods
+                if p.status == "gap" and (satellite is None or p.satellite == satellite)]
+
+    def required_tiles(self, satellite) -> List[str]:
+        for p in self.periods:
+            if p.satellite == satellite:
+                return p.required_tiles
+        return []
+
+    def __repr__(self):
+        return self.summary()
+
+    # ── tabular views ────────────────────────────────────────────────────────
+    def to_dataframe(self):
+        """One row per period × satellite (requires pandas)."""
+        import pandas as pd
+        return pd.DataFrame([
+            {
+                "Period":       p.label,
+                "Start":        p.period_start,
+                "Satellite":    p.satellite,
+                "Status":       p.status,
+                "Tiles needed": p.n_required,
+                "Tiles covered": p.n_covered,
+                "Images":       p.total_usable_images,
+                "Missing tiles": ", ".join(p.missing_tiles) if p.missing_tiles else "-",
+            }
+            for p in self.periods
+        ])
+
+    def tile_dataframe(self):
+        """One row per period × satellite × tile (requires pandas)."""
+        import pandas as pd
+        rows = []
+        for p in self.periods:
+            for t in p.tile_stats:
+                rows.append({
+                    "Period":    p.label,
+                    "Start":     p.period_start,
+                    "Satellite": p.satellite,
+                    "Tile":      t.tile_id,
+                    "Usable":    t.usable_images,
+                    "Total":     t.total_images,
+                    "Best cloud %": round(t.best_cloud, 1) if t.best_cloud != -1 else None,
+                })
+        return pd.DataFrame(rows)
+
+    # ── friendly text summary ────────────────────────────────────────────────
+    def summary(self) -> str:
+        icon = {"available": "[OK] ", "gap": "[GAP]", "missing": "[--] "}
+        word = {
+            "available": "All tiles have usable imagery",
+            "gap":       "Data gap - some tiles missing",
+            "missing":   "No usable imagery",
+        }
+        unit = {"day": "day", "week": "week", "month": "month"}[self.group_by]
+
+        lines = []
+        lines.append("=" * 68)
+        lines.append("  SATELLITE DATA AVAILABILITY REPORT")
+        lines.append("=" * 68)
+        lines.append(f"  Study area (bbox) : {self.aoi_bbox}")
+        lines.append(f"  Date range        : {self.start_date}  ->  {self.end_date}")
+        lines.append(f"  Cloud threshold   : <= {self.max_cloud:.0f}%")
+        lines.append(f"  Grouped by        : {unit}")
+        lines.append("")
+
+        for satellite, periods in self.by_satellite().items():
+            n_req = periods[0].n_required if periods else 0
+            n_ok  = sum(1 for p in periods if p.status == "available")
+            n_gap = sum(1 for p in periods if p.status == "gap")
+            n_no  = sum(1 for p in periods if p.status == "missing")
+
+            lines.append("-" * 68)
+            lines.append(f"  {satellite}  -  needs {n_req} tiles to fully cover your area")
+            lines.append("-" * 68)
+
+            for p in periods:
+                detail = ""
+                if p.status == "gap":
+                    holes = ", ".join(p.missing_tiles[:6])
+                    if len(p.missing_tiles) > 6:
+                        holes += f", +{len(p.missing_tiles) - 6} more"
+                    detail = f"  ({p.n_covered}/{p.n_required} tiles; missing: {holes})"
+                elif p.status == "available":
+                    detail = f"  ({p.total_usable_images} images across {p.n_required} tiles)"
+                lines.append(f"    {icon[p.status]} {p.label:<22} {word[p.status]}{detail}")
+
+            lines.append("")
+            lines.append(f"    Summary: {n_ok} fully-covered {unit}s, "
+                         f"{n_gap} with gaps, {n_no} empty  (of {len(periods)} {unit}s)")
+            lines.append("")
+
+        lines.append("=" * 68)
+        return "\n".join(lines)

clouds_everywhere/providers/__init__.py

@@ -0,0 +1 @@
+from . import sentinel2, landsat, modis

clouds_everywhere/providers/landsat.py

@@ -0,0 +1,51 @@
+from ..models import SatelliteImage, TileResult
+from .utils import fetch_all
+
+URL = "https://earth-search.aws.element84.com/v1/search"
+
+def search(bbox, start_date, end_date, max_cloud):
+    payload = {
+        "collections": ["landsat-c2-l2"],
+        "bbox": bbox,
+        "datetime": f"{start_date}T00:00:00Z/{end_date}T23:59:59Z",
+        "limit": 100,
+    }
+    results = []
+    for item in fetch_all(URL, payload):
+        p = item["properties"]
+        cloud = p.get("eo:cloud_cover", -1)
+        if cloud != -1 and cloud > max_cloud:
+            continue
+        results.append(SatelliteImage(
+            id            = item["id"],
+            date          = p.get("datetime", "")[:10],
+            cloud_cover   = cloud,
+            satellite     = p.get("platform", "Landsat"),
+            thumbnail_url = item["assets"].get("thumbnail", {}).get("href", "")
+        ))
+    return results
+
+
+def search_tiles(bbox, start_date, end_date):
+    """Fetch all Landsat tiles in bbox/range with no cloud filter (used for coverage analysis)."""
+    payload = {
+        "collections": ["landsat-c2-l2"],
+        "bbox": bbox,
+        "datetime": f"{start_date}T00:00:00Z/{end_date}T23:59:59Z",
+        "limit": 100,
+    }
+    results = []
+    for item in fetch_all(URL, payload):
+        p = item["properties"]
+        path = str(p.get("landsat:wrs_path", "?")).zfill(3)
+        row  = str(p.get("landsat:wrs_row",  "?")).zfill(3)
+        results.append(TileResult(
+            tile_id       = f"P{path}R{row}",
+            date          = p.get("datetime", "")[:10],
+            cloud_cover   = p.get("eo:cloud_cover", -1),
+            satellite     = p.get("platform", "Landsat"),
+            item_id       = item["id"],
+            thumbnail_url = item["assets"].get("thumbnail", {}).get("href", ""),
+            geometry      = item.get("geometry"),
+        ))
+    return results

clouds_everywhere/providers/modis.py

@@ -0,0 +1,43 @@
+import requests
+from ..models import SatelliteImage
+
+# NASA CMR STAC — LP DAAC hosts MODIS land surface products
+URL = "https://cmr.earthdata.nasa.gov/stac/LPDAAC_ECS/search"
+COLLECTIONS = ["MOD09GA.061", "MYD09GA.061"]  # Terra + Aqua 500 m daily
+
+def search(bbox, start_date, end_date, max_cloud):
+    payload = {
+        "collections": COLLECTIONS,
+        "bbox": bbox,
+        "datetime": f"{start_date}T00:00:00Z/{end_date}T23:59:59Z",
+        "limit": 100,
+    }
+    try:
+        r = requests.post(URL, json=payload, timeout=30)
+        r.raise_for_status()
+    except requests.RequestException as e:
+        print(f"[MODIS] API error: {e}")
+        return []
+
+    results = []
+    for item in r.json().get("features", []):
+        p = item["properties"]
+        cloud = p.get("eo:cloud_cover", -1)
+        # -1 means the field is absent; include those (cloud status unknown)
+        if cloud != -1 and cloud > max_cloud:
+            continue
+        item_id = item.get("id", "")
+        satellite = "Terra MODIS" if item_id.upper().startswith("MOD") else "Aqua MODIS"
+        assets = item.get("assets", {})
+        thumbnail = (
+            assets.get("browse", {}).get("href", "")
+            or assets.get("thumbnail", {}).get("href", "")
+        )
+        results.append(SatelliteImage(
+            id=item_id,
+            date=p.get("datetime", "")[:10],
+            cloud_cover=cloud,
+            satellite=satellite,
+            thumbnail_url=thumbnail,
+        ))
+    return results

clouds_everywhere/providers/sentinel2.py

@@ -0,0 +1,50 @@
+from ..models import SatelliteImage, TileResult
+from .utils import fetch_all
+
+URL = "https://earth-search.aws.element84.com/v1/search"
+
+def search(bbox, start_date, end_date, max_cloud):
+    payload = {
+        "collections": ["sentinel-2-l2a"],
+        "bbox": bbox,
+        "datetime": f"{start_date}T00:00:00Z/{end_date}T23:59:59Z",
+        "limit": 100,
+    }
+    results = []
+    for item in fetch_all(URL, payload):
+        p = item["properties"]
+        cloud = p.get("eo:cloud_cover", -1)
+        if cloud != -1 and cloud > max_cloud:
+            continue
+        results.append(SatelliteImage(
+            id            = item["id"],
+            date          = p.get("datetime", "")[:10],
+            cloud_cover   = cloud,
+            satellite     = "Sentinel-2",
+            thumbnail_url = item["assets"].get("thumbnail", {}).get("href", "")
+        ))
+    return results
+
+
+def search_tiles(bbox, start_date, end_date):
+    """Fetch all Sentinel-2 tiles in bbox/range with no cloud filter (used for coverage analysis)."""
+    payload = {
+        "collections": ["sentinel-2-l2a"],
+        "bbox": bbox,
+        "datetime": f"{start_date}T00:00:00Z/{end_date}T23:59:59Z",
+        "limit": 100,
+    }
+    results = []
+    for item in fetch_all(URL, payload):
+        p = item["properties"]
+        tile_id = p.get("s2:mgrs_tile") or item["id"].split("_")[1]
+        results.append(TileResult(
+            tile_id       = tile_id,
+            date          = p.get("datetime", "")[:10],
+            cloud_cover   = p.get("eo:cloud_cover", -1),
+            satellite     = "Sentinel-2",
+            item_id       = item["id"],
+            thumbnail_url = item["assets"].get("thumbnail", {}).get("href", ""),
+            geometry      = item.get("geometry"),
+        ))
+    return results

clouds_everywhere/providers/utils.py

@@ -0,0 +1,43 @@
+import time
+import requests
+
+
+def post_with_retry(url, payload, retries=3, backoff=2, timeout=30):
+    """POST with automatic retry on 5xx errors (exponential backoff: 1 s, 2 s, 4 s)."""
+    for attempt in range(retries):
+        r = requests.post(url, json=payload, timeout=timeout)
+        if r.status_code < 500:
+            r.raise_for_status()   # raises on 4xx, returns cleanly on 2xx
+            return r
+        if attempt < retries - 1:
+            time.sleep(backoff ** attempt)
+    r.raise_for_status()
+    return r
+
+
+def fetch_all(url, payload, retries=3, backoff=2, timeout=30):
+    """Collect every feature across all pages of a STAC search.
+
+    The Element84 STAC API caps responses at 100 items per page and signals
+    the next page via a ``links[rel=next].body`` object containing a ``next``
+    cursor token.  Crucially, that body omits any ``filter`` / ``filter-lang``
+    fields from the original request, so we must NOT replace the payload
+    wholesale — we only inject the cursor token into the original payload.
+    """
+    features = []
+    current_payload = payload.copy()
+    while True:
+        r = post_with_retry(url, current_payload, retries=retries, backoff=backoff, timeout=timeout)
+        data = r.json()
+        page = data.get("features", [])
+        features.extend(page)
+        next_link = next(
+            (lnk for lnk in data.get("links", []) if lnk.get("rel") == "next"),
+            None,
+        )
+        if not next_link or not page:
+            break
+        # Only carry the cursor forward — keep the original filter intact.
+        cursor = next_link["body"].get("next")
+        current_payload = {**payload, "next": cursor}
+    return features