forcingkit

Spatiotemporal forcing for computational Earth-system models. forcingkit selects, regrids and serves model-ready time series, with a record of where every value came from.

Animation of the HRRR 10 m wind from the NY Bight to Cape Cod, every 3 hours from 2026-09-22 00:00 to 2026-09-29 12:00 UTC

HRRR 10 m wind served by forcingkit through the 26 to 27 September 2026 nor’easter, NY Bight to Cape Cod, every 3 hours from 22 to 29 September (peak 25.9 m/s), as played by the cache viewer’s time slider.

What it does

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, the NOAA Operational Forecast Systems, NECOFS, HYCOM) that differ in grid type, vertical coordinate, time convention, file layout and access protocol, and 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 (for example through NumericalEarth). For a bounding box and a time window it:

  1. picks the source (the “donor”) best suited to the box, and falls back to the next one if the first cannot deliver;

  2. fetches only the subset it needs, over OPeNDAP, HTTPS or anonymous S3;

  3. interpolates it to a regular longitude/latitude grid and, for the ocean, to fixed z levels in metres;

  4. writes the result as a Zarr store with a versioned schema, its units, and the request that produced it; and

  5. serves the same store again, without refetching, to any later request with the same parameters.

Store names are hashes of the request, including the schema version, so a run can be repeated months later against the same forcing, and a store written under an older schema is never served for a newer request.

What it serves

Route

Delivers

POST /api/v1/obc

The parent ocean (u, v, temperature, salinity, sea surface height) on a regular 0.002 degree grid and fixed z levels, hourly, as schema z-v3. The first record doubles as the initial condition. See Data Fetchers, NECOFS: Northeast Coastal Ocean Forecast System (FVCOM) and NYOFS: NOAA New York/New Jersey Operational Forecast System.

POST /api/v1/atmosphere

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 Atmospheric Forcing Datasets.

POST /api/v1/atmosphere/levels

The air above: HRRR wind, vertical velocity and temperature on its lowest native levels (14 by default, about 10 m to 2.8 km above open water), over the same window and grid as /api/v1/atmosphere, as schema hrrr-levels-v1. For vertical sections and air-parcel tracks in a viewer; not a forcing. See Data Fetchers.

POST /api/v1/waves

NWPS surface waves (significant height, peak period, direction of travel, swell height) and the office’s forcing wind, hourly on the forecast office’s own grid, as schema nwps-waves-v1. NOMADS reaches back about five days; older windows come from a configured archive. See Surface Waves (NWPS).

POST /api/v1/rivers

Freshwater discharge at each listed river mouth in the box, hourly, from the tide-free USGS stream gauges upstream (chosen per request) scaled to the drainage area at the mouth, as schema river-v1. See River Discharge.

POST /api/v1/tide

Observed water level at a NOAA CO-OPS station, for validation.

POST /api/v1/ndbc

NDBC buoy meteorology and ADCP current profiles, for validation.

POST /api/v1/telemetry/station, POST /api/v1/telemetry/bbox

Water-column profiles from the UConn Marine Sciences ERDDAP server, by station or by box.

POST /api/v1/jobs/obc, POST /api/v1/jobs/atmosphere, POST /api/v1/jobs/waves, GET /api/v1/jobs/{id}

The parent-ocean, atmosphere and waves builds as queued jobs, each result a STAC Item, and the finished stores read-only over HTTP at /api/v1/stores/. Used by the Python client; see Python client and trajectories.

/api/v1/cache/... and /ui/

The cache viewer: an inventory of every store, with a coverage map and timeline and 2D and 3D previews. See Cache viewer.

Each generating route has /download/{zarr_id} and, for the parent ocean, /cache and /predict-donor companions. The running service publishes its full OpenAPI description at /docs.

From Python, the forcingkit-client package wraps these routes, returns xarray objects, and interpolates forcing along a trajectory (a tagged animal, a vessel, a drifter); see Python client and trajectories.

Parent-ocean donors at a glance

Donor

Model and grid

Resolution

Coverage served

Status in forcingkit

NYOFS

POM, curvilinear, 7 sigma levels

About 140 to 1000 m (median 340 m)

NY/NJ Harbor; 2014 to the present

Legacy output, not z-v3

DBOFS

ROMS, curvilinear

About 100 m

Delaware Bay and offshore New Jersey

Legacy output, not z-v3

NECOFS

FVCOM GOM7, unstructured, 45 sigma layers

About 130 to 800 m in the NY Harbor and Long Island Sound region

Gulf of Maine to the Mid-Atlantic Bight; daily archive from 2025-01-01

Streams z-v3 hour by hour; the recommended donor

HYCOM

HYCOM GLBv0.08, GLBy0.08 and ESPC-D-V02, regular

1/12 degree (about 9 km)

Global; 1994 to the present

Legacy output; last-resort fallback; tidal only from 2024-09-05

Doppio (ROMS, about 7 km, 40 s-levels; an hourly reanalysis for 2007 to 2024 and a real-time system from 2017) is read as a full-depth subset for comparison with NECOFS, not yet as a parent-ocean donor. Northeast Shelf Models and Reanalyses surveys the other models and reanalyses of the region.

Quick start

uv sync
uv run uvicorn service.forcingkit_serve.main:app --port 9598

Then request 24 hours of parent ocean for a box in central Long Island Sound, which NECOFS serves:

curl -s -X POST http://localhost:9598/api/v1/obc \
  -H 'Content-Type: application/json' \
  -d '{"bbox": {"min_lon": -73.20, "min_lat": 40.95, "max_lon": -73.00, "max_lat": 41.10},
       "start_date": "2026-09-26T00:00:00Z", "duration_hours": 24}'

The response names the store (zarr_id, zarr_path, download_url), the donor that delivered it (donor) and the donor ranked first for the box (predicted_donor). A second identical request returns "status": "cached" immediately. Stores live under FORCINGKIT_CACHE_DIR (default ~/.cache/forcingkit).

The data forcingkit serves belongs to the institutions that produce it; Sources and Citations lists them, with their terms of use and the papers to cite.

Contributions are welcome, from a corrected archive path to a new region. Roadmap and Contributing lists the parent-ocean and atmosphere sources that would add most next, coverage first and resolution second (Copernicus GLO12 and GLORYS12, the remaining NOAA forecast systems, the Doppio reanalysis, HRRR Alaska, and a first European pair from Copernicus Marine among them), and what a new source needs.

Source, issues and releases: https://github.com/lhzn-io/forcingkit. The package is published on PyPI as forcingkit.