forcingkit 0.4.0__tar.gz → 0.6.0__tar.gz

{forcingkit-0.4.0 → forcingkit-0.6.0}/.env.template

@@ -2,8 +2,12 @@
 # Copy this file to .env and fill in your credentials.
 # A docker-compose service can load it with env_file.
 
-# No credentials are required at present: HRRR, NOAA OFS, NECOFS, HYCOM, NDBC and
-# CO-OPS are all served without authentication.
+# No credentials are required: HRRR, NOAA OFS, NECOFS, HYCOM, NDBC, CO-OPS and the
+# USGS Water Data APIs are all served without authentication.
+
+# Optional USGS Water Data API key (free from https://api.waterdata.usgs.gov/signup/).
+# Without it, river discharge requests still work at a lower hourly rate limit.
+# USGS_API_KEY=
 
 # Cache root for every store (default ~/.cache/forcingkit). The old name
 # ECODATA_CACHE_CACHE_DIR is still read, with a warning, until the next release.

{forcingkit-0.4.0 → forcingkit-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forcingkit
-Version: 0.4.0
+Version: 0.6.0
 Summary: Spatiotemporal forcing for computational Earth-system models: selects, regrids and serves model-ready time series with provenance.
 Project-URL: Documentation, https://forcingkit.docs.lhzn.io
 Project-URL: Issues, https://github.com/lhzn-io/forcingkit/issues

{forcingkit-0.4.0 → forcingkit-0.6.0}/docs/source/conf.py

@@ -9,7 +9,7 @@ sys.path.insert(0, os.path.abspath("../../src"))
 project = "forcingkit"
 copyright = "2026, Long Horizon Observatory"
 author = "Daniel Fry"
-release = "0.4.0"
+release = "0.6.0"
 
 extensions = [
     "sphinx.ext.autodoc",

{forcingkit-0.4.0 → forcingkit-0.6.0}/docs/source/index.rst

@@ -17,13 +17,15 @@ and serves model-ready time series, with a record of where every value came from
 What it does
 ------------
 
-A regional ocean model needs two things from outside its own domain: the state of a larger
-"parent" ocean along its open boundaries, and the atmosphere above its surface. Both come from
+A regional ocean model needs three things from outside its own domain: the state of a larger
+"parent" ocean along its open boundaries, the atmosphere above its surface, and the rivers that
+flow into it. The first two come from
 operational and archive systems (NOAA's `HRRR <https://rapidrefresh.noaa.gov/hrrr/>`__, the NOAA
 `Operational Forecast Systems <https://tidesandcurrents.noaa.gov/models.html>`__,
 `NECOFS <https://fvcom.smast.umassd.edu/?p=20>`__, `HYCOM <https://www.hycom.org/>`__) that
 differ in grid type, vertical coordinate, time convention, file layout and access protocol, and
-that change those details without notice.
+that change those details without notice. River discharge comes from stream gauges, which
+measure flow upstream of the head of tide rather than at the mouth.
 
 forcingkit is a FastAPI service that sits between those providers and model codes such as
 `Oceananigans.jl <https://github.com/CliMA/Oceananigans.jl>`__ (for example through
@@ -61,6 +63,10 @@ What it serves
      - HRRR surface fields (10 m wind, 2 m temperature and humidity, pressure, radiation,
        precipitation) on a regular 0.03 degree grid, hourly, as schema ``hrrr-atm-v1``. See
        :doc:`atmospheric_forcing`.
+   * - ``POST /api/v1/rivers``
+     - Freshwater discharge at each listed river mouth in the box, hourly, from the tide-free
+       `USGS <https://waterdata.usgs.gov/>`__ stream gauges upstream (chosen per request) scaled
+       to the drainage area at the mouth, as schema ``river-v1``. See :doc:`rivers`.
    * - ``POST /api/v1/tide``
      - Observed water level at a `NOAA CO-OPS <https://tidesandcurrents.noaa.gov/>`__ station, for
        validation.
@@ -154,6 +160,7 @@ PyPI as ``forcingkit``.
    nyofs
    hycom
    atmospheric_forcing
+   rivers
 
 .. toctree::
    :maxdepth: 1

forcingkit-0.6.0/docs/source/rivers.rst

@@ -0,0 +1,177 @@
+River Discharge
+===============
+
+``POST /api/v1/rivers`` delivers hourly freshwater discharge at the mouth of every listed river
+in a box (or at mouths passed with the request), for point or surface sources in an ocean model. A nested regional model otherwise
+receives river water only through its open boundaries and initial state, so a river that enters
+inside the domain is missing as a source and its freshwater decays over the run.
+
+Method
+------
+
+The method is common practice for gauge-driven river forcing. The NOAA Operational Forecast
+Systems map US Geological Survey real-time gauges onto model cells with a per-river scale factor
+and fall back to climatology. Regional estuary models scale gauged flow to ungauged area by the
+ratio of drainage areas.
+
+1. **Gauges, derived for every request.** Only a river's mouth is listed. From its NHDPlus
+   outlet flowline, forcingkit asks the USGS `NLDI <https://waterdata.usgs.gov/blog/nldi-intro/>`__
+   for every USGS site upstream, then keeps a site if:
+
+   - USGS classes it as a stream site (``ST``). Tidal streams (``ST-TS``) and estuaries (``ES``)
+     are left out, because their flow reverses with the tide; on the Connecticut River that rules
+     out Hartford and Middle Haddam;
+   - it has a drainage area, and a discharge record (15-minute or daily) covering the window;
+   - it drains at least ``min_share`` of the mouth's area (default 0.01), so headwater brooks
+     drop out;
+   - no other kept site lies downstream of it, which leaves the lowest gauge on each branch.
+
+   The kept gauges then measure disjoint parts of the basin. The selection follows the window: a
+   gauge that opened in 2010 is used from 2010 on, and one that closed is dropped from then on.
+2. **Discharge at the mouth.** The sum of the river's gauges, scaled by the drainage area at the
+   mouth over the gauged area:
+
+   .. math::
+
+      Q_\text{mouth} = \frac{A_\text{mouth}}{\sum_k A_k} \sum_k Q_k
+
+   Gauge areas come from the USGS monitoring-location records; the mouth's area is that of the
+   outlet's NLDI basin.
+3. **Time base.** The 15-minute record from the USGS Water Data APIs (``continuous``), averaged to
+   hourly values centred on the hour. The store holds ``hours + 1`` records, from ``start_time``
+   to ``start_time + hours``.
+4. **Gaps.** A gap of up to ``max_gap_hours`` (default 6) with values on both sides is
+   interpolated. A longer gap takes that day's mean from the ``daily`` record. A day with neither
+   is an error, unless ``allow_climatology`` is set; then it takes the USGS day-of-year median of
+   daily flow. Every filled hour is flagged in ``fill`` (0 measured, 1 interpolated, 2 daily
+   mean, 3 climatology median), and the store's ``provenance`` attribute counts them per river.
+5. **Water properties.** Salinity is zero. Water temperature (``temperature``) comes from the first
+   gauge on the river that measures it (USGS parameter 00010), and is NaN where none does.
+6. **Provisional data.** USGS values are provisional until approved, typically months later, and
+   provisional values are revised. A store containing any provisional value is marked
+   ``provisional = True`` and is served from the cache for one day only; after that a request
+   rebuilds it.
+7. **Travel time.** None by default. A mouth entry may set ``lag_hours``; gauge values are then
+   taken that many hours earlier.
+
+Mouths
+------
+
+Mouths are listed in ``forcingkit/data/rivers/*.json`` and in any ``*.json`` file in the directory
+named by ``FORCINGKIT_RIVER_MOUTHS_DIR``; a later entry with the same name replaces an earlier one.
+A request may instead pass its own ``mouths``. Adding a river needs a mouth entry and no code or
+release:
+
+.. code-block:: json
+
+   {"mouths": [
+     {"name": "Connecticut", "lon": -72.3305, "lat": 41.2726, "comid": 7703046},
+     {"name": "Saugatuck", "lon": -73.36, "lat": 41.10, "trace_from": "USGS-01208990"}
+   ]}
+
+- ``name``, ``lon``, ``lat`` (required): the point places the mouth for the bbox test.
+- ``comid``: the NHDPlus outlet flowline. Otherwise ``trace_from`` names any NLDI feature on the
+  river (a USGS site such as ``USGS-01184000``) and the outlet is the end of its downstream trace.
+  Failing both, the point is snapped to the nearest flowline, with a warning: at an estuary the
+  nearest flowline can be a short coastal one rather than the river.
+- ``include`` and ``exclude``: USGS site numbers to pin or rule out where judgement beats the rule
+  (for example a gauge below a dam whose releases should not drive the forcing). A pinned set that
+  drains more than the mouth's area is refused as double counting.
+- ``lag_hours``: travel time from the gauges to the mouth, applied to the gauge window.
+
+The id of a store includes the mouth entries and ``min_share``, but not the derived gauges, which
+are recorded in the store instead. NLDI facts about a mouth (its outlet, basin area, upstream sites
+and which sites lie downstream of which) are cached for 30 days under ``usgs/derivations`` in the
+cache directory, so only the first request for a mouth takes long (about a minute for the
+Connecticut, whose basin holds 1,375 USGS sites).
+
+The packaged mouths are the rivers into Long Island Sound. For a request over the Sound in April
+2026 the derivation chose:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 16 46 13 13 12
+
+   * - River
+     - USGS gauges kept
+     - Gauged (mi²)
+     - Mouth (mi²)
+     - Scale
+   * - Housatonic
+     - 01205500 at Stevenson; 01208500 Naugatuck at Beacon Falls
+     - 1,804
+     - 1,944
+     - 1.08
+   * - Quinnipiac
+     - 01196500 at Wallingford; 01196620 Mill River near Hamden; 01196561 Muddy River near East
+       Wallingford
+     - 148
+     - 204
+     - 1.37
+   * - Connecticut
+     - 01184000 at Thompsonville; 01189995 Farmington at Tariffville
+     - 10,237
+     - 11,242
+     - 1.10
+   * - Thames
+     - 01127000 Quinebaug at Jewett City; 011230695 Shetucket at Taftville; 01127500 Yantic at
+       Yantic
+     - 1,314
+     - 1,470
+     - 1.12
+
+The Quinnipiac's outlet basin is New Haven Harbor's, so its scaled flow also stands for the
+harbour's other streams. The Housatonic at Stevenson is below a hydroelectric dam, so its hourly
+flow follows the dam's releases. The Bronx River gauge (01302020) has no record before the 2000s,
+so a request for an earlier window fails unless ``skip_ungauged`` is set, which leaves such a
+river out and lists it in the store's ``skipped_rivers``.
+
+Request and store
+-----------------
+
+.. code-block:: bash
+
+   curl -s -X POST localhost:9598/api/v1/rivers -H 'Content-Type: application/json' -d '{
+     "bbox": {"min_lon": -73.855, "min_lat": 40.75, "max_lon": -71.9, "max_lat": 41.45},
+     "start_time": "2026-04-02T00:00:00Z", "hours": 48}'
+
+Optional fields: ``mouths``, ``min_share`` (default 0.01), ``max_gap_hours`` (default 6),
+``allow_climatology`` and ``skip_ungauged`` (both default false), and ``cache_bust``.
+
+For that request (four rivers, 49 records), the mean discharges over the 48 hours were 1,553 m³/s
+for the Connecticut, 147 for the Housatonic, 148 for the Thames and 13 for the Quinnipiac.
+
+The store (schema ``river-v1``) has a ``river`` dimension:
+
+- ``discharge`` (time, river): m³ s⁻¹, ``water_volume_transport_in_river_channel``.
+- ``temperature`` (time, river): °C.
+- ``fill`` (time, river): the flags above.
+- ``mouth_lon``, ``mouth_lat``, ``scale_factor``, ``salinity`` (river).
+- Attributes: ``river_names``; ``provenance`` (JSON: per river, the gauges kept, the areas, the
+  scale factor, the outlet, and the dropped candidates counted by reason); ``derivation_dropped``
+  (JSON: every dropped candidate with its reason); ``skipped_rivers``; ``provisional``; and
+  ``built_utc``.
+
+A JSON sidecar next to the store repeats the request, the mouths and the derivation. ``GET /api/v1/rivers/download/{zarr_id}``
+returns the store as a zip.
+
+Credentials
+-----------
+
+None are required. A free USGS Water Data API key (``USGS_API_KEY``, from
+`api.waterdata.usgs.gov/signup <https://api.waterdata.usgs.gov/signup/>`__) raises the hourly rate
+limit; it is sent in the ``X-Api-Key`` header. forcingkit uses the modernized APIs, not the
+legacy ``waterservices.usgs.gov``, which USGS plans to retire in 2027.
+
+Limits
+------
+
+- Mouths are not found automatically within a box: each river needs a mouth entry. Finding
+  coastal outlets from NHDPlus would remove that step.
+- The selection rule cannot tell a regulated gauge from a natural one; use ``exclude`` where dam
+  operations should not reach the forcing.
+- Gauges measure surface runoff. Groundwater discharge (most of Long Island's freshwater input) is
+  not represented.
+- A model that applies discharge as a surface freshwater flux on fixed levels dilutes salinity
+  but adds no volume. Whether the volume is added depends on the model's vertical coordinate, not
+  on this store.

{forcingkit-0.4.0 → forcingkit-0.6.0}/docs/source/roadmap.rst

@@ -1,9 +1,10 @@
 Roadmap and Contributing
 ========================
 
-As of 2026-10-06. This page covers the two kinds of forcing forcingkit delivers: the **parent
-ocean** for a model's open boundaries (``/api/v1/obc``) and the **surface atmosphere**
-(``/api/v1/atmosphere``). New sources are ranked by two questions:
+As of 2026-10-09. This page covers the kinds of forcing forcingkit delivers: the **parent
+ocean** for a model's open boundaries (``/api/v1/obc``), the **surface atmosphere**
+(``/api/v1/atmosphere``) and **river discharge** (``/api/v1/rivers``). New sources are ranked by
+two questions:
 
 1. **Coverage first.** Does it serve a region, or a span of years, that no current source does?
 2. **Resolution second.** Where something already serves, does it resolve the coast better?
@@ -44,6 +45,10 @@ Current coverage
      - Contiguous US (atmosphere)
      - 2014-07-30 on
      - 3 km
+   * - :doc:`USGS gauges <rivers>`
+     - Rivers into Long Island Sound (river discharge)
+     - 15-minute values online from about 2007; daily means fill in further back
+     - Five river mouths
 
 So today the only parent ocean outside the US Northeast is HYCOM, at 1/12 degree and in the
 legacy output layout, and there is no atmosphere outside the contiguous US: there, and before
@@ -73,6 +78,41 @@ Planned work
        hindcasts (:doc:`atmospheric_forcing`).
    * - Cache policy
      - Invalidate stores built from forecasts when the upstream system publishes a newer cycle.
+   * - A second global parent
+     - HYCOM is the only parent ocean for current dates outside the US Northeast, and its server
+       (``tds.hycom.org``) often stalls past the read timeout (:doc:`hycom`). Copernicus GLO12
+       (see `Global parent ocean`_) would give an independent fallback for 2020-11-01 on.
+   * - Warn on gaps in a donor's record
+     - Every HYCOM experiment has a few gaps of up to 51 hours in its 3-hourly record, and the
+       hourly resampling bridges them by linear interpolation without notice. Log a warning,
+       and record the gap in the store's attributes, when a window contains a step longer than
+       about 6 hours.
+   * - HYCOM fetcher clean-up
+     - Remove the unused ``_normalize_lons``. Select the initial-condition time by position, as
+       the boundary path does: the nearest-label lookup fails on the non-monotonic time axis of
+       GLBv0.08 ``expt_93.0``.
+   * - River mouths for more regions, and found automatically
+     - :doc:`rivers` derives each river's gauges per request, so a new river needs only a mouth
+       entry. Mouths for the Hudson, Raritan and Delaware would cover the NY Bight and Delaware Bay
+       parents already served; finding coastal outlets in a box from NHDPlus would remove the
+       entries altogether.
+   * - Ungauged rivers
+     - Where no tide-free gauge exists, the `National Water Model
+       <https://water.noaa.gov/about/nwm>`__ retrospective and operational streamflow (on AWS)
+       could supply discharge at the outlet reach.
+   * - mypy hook without an active environment
+     - The ``mypy`` pre-commit hook runs the ``mypy`` on ``PATH``, so a commit made without the
+       project environment activated fails with "Executable ``mypy`` not found". Run it through
+       ``uv run`` so it works from any shell.
+   * - Fetcher module names
+     - Modules in ``forcingkit.fetchers`` are named for their source (``necofs``, ``hycom``,
+       ``ndbc``, ``coastwatch``, ``usgs``), and a model-ready delivery for the source and what it
+       delivers (``hrrr_atmosphere``, ``usgs_rivers``). Three predate the convention:
+       ``noaa.py`` serves CO-OPS water levels and current predictions (``coops.py``),
+       ``erddap.py`` serves the UConn profile stations (named for the protocol, not the source),
+       and ``hydrography.py`` finds heads of tide from OpenStreetMap (``osm.py`` or similar).
+       Renaming them breaks imports from earlier releases, so it belongs in a release that says
+       so, with the old names kept as deprecated aliases for one release.
 
 Candidate sources: coverage
 ---------------------------

{forcingkit-0.4.0 → forcingkit-0.6.0}/docs/source/sources.rst

@@ -49,6 +49,21 @@ Providers
    * - NDBC buoys
      - `NOAA National Data Buoy Center <https://www.ndbc.noaa.gov/>`__
      - NOAA attribution.
+   * - River discharge
+     - `US Geological Survey <https://www.usgs.gov/>`__ stream gauges, through the `USGS Water
+       Data APIs <https://api.waterdata.usgs.gov/>`__; drainage areas from the USGS `NLDI
+       <https://waterdata.usgs.gov/blog/nldi-intro/>`__ and NHDPlus
+     - Cite the gauges as "U.S. Geological Survey, USGS Water Data for the Nation", with the site
+       numbers in the store's ``provenance``. USGS data are in the public domain; provisional
+       values are subject to revision.
+   * - Satellite surface fields
+     - `NOAA NESDIS CoastWatch <https://coastwatch.noaa.gov/>`__ ERDDAP servers: VIIRS
+       chlorophyll-a and Kd490 (S-NPP, NOAA-20, NOAA-21), Sentinel-3 OLCI chlorophyll-a, and the
+       gap-filled DINEOF products; MUR sea surface temperature from `NASA JPL
+       <https://podaac.jpl.nasa.gov/>`__ (PO.DAAC), served through CoastWatch
+     - Acknowledge NOAA NESDIS CoastWatch and the datasets named in the store's ``products``
+       attribute. MUR: JPL MUR MEaSUREs Project (2015) and Chin et al. (2017). OLCI and DINEOF
+       products require "Contains modified Copernicus Sentinel data [year]".
    * - Water-column profiles
      - `University of Connecticut Department of Marine Sciences
        <https://marinesciences.uconn.edu/>`__ (`ERDDAP
@@ -91,6 +106,9 @@ References
   estuaries. *Journal of Atmospheric and Oceanic Technology*, 20(1), 159-186.
   `doi:10.1175/1520-0426(2003)020<0159:AUGFVT>2.0.CO;2
   <https://doi.org/10.1175/1520-0426(2003)020%3C0159:AUGFVT%3E2.0.CO;2>`__
+- Chin, T. M., J. Vazquez-Cuervo and E. M. Armstrong (2017). A multi-scale high-resolution
+  analysis of global sea surface temperature. *Remote Sensing of Environment*, 200, 154-169.
+  `doi:10.1016/j.rse.2017.07.029 <https://doi.org/10.1016/j.rse.2017.07.029>`__
 - Dowell, D. C., C. R. Alexander, E. P. James, et al. (2022). The High-Resolution Rapid Refresh
   (HRRR): An hourly updating convection-allowing forecast model. Part I: Motivation and system
   description. *Weather and Forecasting*, 37(8), 1371-1395.
@@ -102,6 +120,9 @@ References
   (HRRR): An hourly updating convection-allowing forecast model. Part II: Forecast performance.
   *Weather and Forecasting*, 37(8), 1397-1417.
   `doi:10.1175/WAF-D-21-0130.1 <https://doi.org/10.1175/WAF-D-21-0130.1>`__
+- JPL MUR MEaSUREs Project (2015). GHRSST Level 4 MUR Global Foundation Sea Surface
+  Temperature Analysis (v4.1). PO.DAAC, CA, USA.
+  `doi:10.5067/GHGMR-4FJ04 <https://doi.org/10.5067/GHGMR-4FJ04>`__
 - NOAA (2002). *Implementation Plan, Port of New York and New Jersey Operational Forecast System
   (NYOFS)*. NOAA Technical Report NOS CO-OPS 37, Silver Spring, MD.
   `PDF <https://tidesandcurrents.noaa.gov/publications/techrpt37.pdf>`__

{forcingkit-0.4.0 → forcingkit-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forcingkit"
-version = "0.4.0"
+version = "0.6.0"
 description = "Spatiotemporal forcing for computational Earth-system models: selects, regrids and serves model-ready time series with provenance."
 readme = "README.md"
 requires-python = ">=3.11"

{forcingkit-0.4.0 → forcingkit-0.6.0}/service/forcingkit_serve/main.py

@@ -589,6 +589,226 @@ def download_atmosphere(zarr_id: str):
     )
 
 
+class RiverRequest(BaseModel):
+    bbox: BoundingBox
+    start_time: str  # ISO 8601, UTC
+    hours: int
+    max_gap_hours: int = 6
+    allow_climatology: bool = False
+    # Mouths to serve instead of the listed ones in the bbox: each {name, lon, lat} with
+    # optional comid or trace_from (the outlet), include / exclude (USGS site numbers) and
+    # lag_hours.
+    mouths: List[Dict[str, Any]] | None = None
+    # Gauges draining less than this share of the mouth's area are left out.
+    min_share: float = 0.01
+    # Leave out, rather than fail on, a river with no gauge record over the window.
+    skip_ungauged: bool = False
+    cache_bust: bool = False
+
+
+def _river_cache_dir() -> str:
+    return settings.cache_dir("rivers")
+
+
+@app.post("/api/v1/rivers")
+def generate_rivers(request: RiverRequest) -> Dict[str, Any]:
+    """Hourly discharge at each river mouth in the bbox (or each of `mouths`), for point sources
+    in an ocean model: the lowest tide-free USGS gauge on each branch, derived per request from
+    USGS NLDI and site metadata, summed and scaled by drainage area, from `start_time` to
+    `start_time + hours`, streamed to a Zarr store."""
+    import json
+
+    import zarr
+
+    from forcingkit.dispatcher import dispatch_river_request, river_key, river_mouths
+
+    if request.hours < 1:
+        raise HTTPException(status_code=400, detail="hours must be at least 1")
+    if request.max_gap_hours < 0:
+        raise HTTPException(status_code=400, detail="max_gap_hours must be at least 0")
+    if not 0 <= request.min_share < 1:
+        raise HTTPException(status_code=400, detail="min_share must be in [0, 1)")
+    bbox_list = [
+        request.bbox.min_lon,
+        request.bbox.min_lat,
+        request.bbox.max_lon,
+        request.bbox.max_lat,
+    ]
+    try:
+        mouths = river_mouths(bbox_list, request.mouths)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    if not mouths:
+        raise HTTPException(
+            status_code=400, detail=f"no listed river mouth lies in bbox {bbox_list}"
+        )
+    zarr_id = river_key(
+        bbox_list,
+        request.start_time,
+        request.hours,
+        request.max_gap_hours,
+        request.allow_climatology,
+        mouths,
+        request.min_share,
+        request.skip_ungauged,
+    )
+    os.makedirs(_river_cache_dir(), exist_ok=True)
+    zarr_path = os.path.join(_river_cache_dir(), f"{zarr_id}.zarr")
+    try:
+        final_path = dispatch_river_request(
+            bbox_list,
+            request.start_time,
+            request.hours,
+            zarr_path,
+            max_gap_hours=request.max_gap_hours,
+            allow_climatology=request.allow_climatology,
+            cache_bust=request.cache_bust,
+            mouths=mouths,
+            min_share=request.min_share,
+            skip_ungauged=request.skip_ungauged,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"River delivery failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+    attrs = dict(zarr.open_group(final_path, mode="r", zarr_format=2).attrs)
+    return {
+        "status": "success",
+        "zarr_id": zarr_id,
+        "zarr_path": final_path,
+        "download_url": f"/api/v1/rivers/download/{zarr_id}",
+        "rivers": json.loads(str(attrs.get("provenance", "[]"))),
+        "provisional": bool(attrs.get("provisional", False)),
+        "skipped_rivers": json.loads(str(attrs.get("skipped_rivers", "[]"))),
+    }
+
+
+@app.get("/api/v1/rivers/download/{zarr_id}")
+def download_rivers(zarr_id: str):
+    search_id = zarr_id if zarr_id.startswith("riv_") else f"riv_{zarr_id}"
+    if not search_id[4:].isalnum():
+        raise HTTPException(status_code=400, detail="invalid store id")
+    cache_dir = _river_cache_dir()
+    zarr_path = os.path.join(cache_dir, f"{search_id}.zarr")
+    if not os.path.isdir(zarr_path):
+        raise HTTPException(status_code=404, detail="River Zarr store not found.")
+    zip_path = os.path.join(cache_dir, f"{search_id}.zip")
+    if _zip_is_stale(zip_path, zarr_path):
+        shutil.make_archive(zip_path.replace(".zip", ""), "zip", zarr_path)
+    return FileResponse(
+        zip_path, media_type="application/zip", filename=f"{search_id}.zip"
+    )
+
+
+class SatelliteRequest(BaseModel):
+    bbox: BoundingBox
+    quantity: (
+        str  # "sst", "chlor_a", "kd_490" or "spm" (see fetchers.coastwatch.QUANTITIES)
+    )
+    end_time: str | None = None  # ISO 8601, UTC; default now
+    days: int = 7
+    coast_pixels: int = 1
+    cache_bust: bool = False
+
+
+def _satellite_cache_dir() -> str:
+    return settings.cache_dir("satellite")
+
+
+def _satellite_retention_days() -> float:
+    return float(settings.env("FORCINGKIT_SATELLITE_RETENTION_DAYS", "30") or 30)
+
+
+@app.post("/api/v1/satellite")
+def get_satellite(request: SatelliteRequest) -> Dict[str, Any]:
+    """A satellite surface field over the bbox: each pixel's most recent valid value across the quantity's sensors
+    within `days` of `end_time`, with its age, a band of `coast_pixels` masked along the shore, as a Zarr store.
+
+    Stores older than FORCINGKIT_SATELLITE_RETENTION_DAYS (default 30) are pruned on every request, so the cache
+    stays bounded.
+    """
+    import json
+    from datetime import datetime, timezone
+
+    import pandas as pd
+
+    from forcingkit.fetchers import coastwatch
+
+    products = coastwatch.QUANTITIES.get(request.quantity)
+    if products is None:
+        raise HTTPException(
+            status_code=400,
+            detail=f"quantity must be one of {sorted(coastwatch.QUANTITIES)}",
+        )
+    if not 1 <= request.days <= 31:
+        raise HTTPException(status_code=400, detail="days must be 1 to 31")
+    end = (
+        pd.Timestamp(request.end_time).to_pydatetime()
+        if request.end_time
+        else datetime.now(timezone.utc)
+    )
+    bbox_list = [
+        request.bbox.min_lon,
+        request.bbox.min_lat,
+        request.bbox.max_lon,
+        request.bbox.max_lat,
+    ]
+    cache_dir = _satellite_cache_dir()
+    os.makedirs(cache_dir, exist_ok=True)
+    coastwatch.prune_cache(cache_dir, _satellite_retention_days())
+    zarr_id = coastwatch.cache_key(
+        products, bbox_list, end, request.days, request.coast_pixels
+    )
+    zarr_path = os.path.join(cache_dir, f"{zarr_id}.zarr")
+    if request.cache_bust or not os.path.isdir(zarr_path):
+        try:
+            ds = coastwatch.mask_coast(
+                coastwatch.composite(products, bbox_list, end, request.days),
+                request.coast_pixels,
+            )
+        except ValueError as e:
+            raise HTTPException(status_code=404, detail=str(e))
+        except Exception as e:
+            logger.error(f"Satellite delivery failed: {e}")
+            raise HTTPException(status_code=500, detail=str(e))
+        shutil.rmtree(zarr_path, ignore_errors=True)
+        ds.to_zarr(zarr_path, mode="w", zarr_format=2)
+    import xarray as xr
+
+    ds = xr.open_zarr(zarr_path)
+    valid = ds["value"].notnull()
+    return {
+        "status": "success",
+        "zarr_id": zarr_id,
+        "zarr_path": zarr_path,
+        "download_url": f"/api/v1/satellite/download/{zarr_id}",
+        "products": str(ds.attrs.get("products", "")).split(","),
+        "attribution": ds.attrs.get("attribution", ""),
+        "valid_share": float(valid.mean()),
+        "age_days_median": float(ds["age_days"].where(valid).median())
+        if bool(valid.any())
+        else None,
+        "attrs": json.loads(json.dumps(dict(ds.attrs), default=str)),
+    }
+
+
+@app.get("/api/v1/satellite/download/{zarr_id}")
+def download_satellite(zarr_id: str):
+    if not (zarr_id.startswith("sat_") and zarr_id[4:].isalnum()):
+        raise HTTPException(status_code=400, detail="invalid store id")
+    cache_dir = _satellite_cache_dir()
+    zarr_path = os.path.join(cache_dir, f"{zarr_id}.zarr")
+    if not os.path.isdir(zarr_path):
+        raise HTTPException(status_code=404, detail="Satellite Zarr store not found.")
+    zip_path = os.path.join(cache_dir, f"{zarr_id}.zip")
+    if _zip_is_stale(zip_path, zarr_path):
+        shutil.make_archive(zip_path.replace(".zip", ""), "zip", zarr_path)
+    return FileResponse(
+        zip_path, media_type="application/zip", filename=f"{zarr_id}.zip"
+    )
+
+
 if __name__ == "__main__":
     import uvicorn
     import argparse

forcingkit-0.6.0/src/forcingkit/data/rivers/northeast_us.json

@@ -0,0 +1,29 @@
+{
+  "region": "Long Island Sound and its approaches, US Northeast",
+  "note": "River mouths only. The gauges and the scale factor of each river are derived for every request from USGS NLDI and site metadata (see forcingkit.fetchers.usgs_rivers). comid is the NHDPlus outlet flowline; lon and lat place the mouth for the bbox test. include and exclude pin or rule out gauges by USGS site number.",
+  "mouths": [
+    {
+      "name": "Bronx",
+      "lon": -73.8584,
+      "lat": 40.8032,
+      "comid": 26431899,
+      "note": "Enters the East River at Clason Point. The outlet is set by hand: NHDPlus routes the East River on through New York Harbor."
+    },
+    {"name": "Housatonic", "lon": -73.1113, "lat": 41.1714, "comid": 7718580},
+    {
+      "name": "Quinnipiac",
+      "lon": -72.9053,
+      "lat": 41.2981,
+      "comid": 6178614,
+      "note": "The outlet basin is New Haven Harbor's, so the scaled flow also stands for the Mill and West Rivers."
+    },
+    {
+      "name": "Connecticut",
+      "lon": -72.3305,
+      "lat": 41.2726,
+      "comid": 7703046,
+      "note": "Travel time from Thompsonville to the mouth is roughly a day at high flow; set lag_hours to apply it."
+    },
+    {"name": "Thames", "lon": -72.0827, "lat": 41.3178, "comid": 6170754}
+  ]
+}