River gauging station along urban river reach with calibrated stage response envelope

CALIBRATED HYDROLOGICAL FORECASTING

River Response API — Calibrated rainfall-to-surge level & lag foresight.

A calibrated estimate of how rainfall in different upstream sub-catchments translates to later stage rises and discharge at river sensors. Features time-to-peak lag, crest surge height, and an explicit 90% confidence uncertainty envelope.

AVAILABLE · POST ENDPOINTSee how it works ↓

Illustrative agriculture imagery

THE DECISION IT SUPPORTS

How high will the river rise at our gauging sensor—and exactly when will it crest?

Using antecedent soil moisture conditions, tributary rainfall intensity, and historical sensor calibration data, AtmosGrid models downstream stage rise and lag time. The response includes an explicit uncertainty band and discloses the historical hydrographs behind the calibration.

Built for

River sensor network operators
Catchment flood warning authorities
Hydrological digital twin platforms
Municipal flood defense & siren controllers

WHY TEAMS USE IT

Turn broad data into a clearer next step.

Each result is designed to narrow a decision, show the inputs behind it, and surface what must still be checked locally.

Gain 3 to 8 hours of advance warning

Anticipate flood crests hours before upstream runoff gathers at the downstream river sensor.

Make decisions with transparent uncertainty

Act on the 90% confidence interval [min, max] rather than an over-confident single point estimate.

Pinpoint surge tributary drivers

Know which upstream branch is responsible for the surge to target sluice gates, weir operations, and flood diversions.

Calibration integrity

Clearly flags when a model is preliminary vs fully calibrated against historical storm events.

FROM REGION TO FIELD

See where each signal fits.

Images illustrate the operational setting. They are not live observations; use source timestamps and local measurements for decisions.

Predicted crest level with 90% confidence bounds
Translates upstream rainfall into a downstream stage hydrograph and lag time with explicit uncertainty.

Runoff coefficient governed by ground saturation
Soil moisture governs whether 30mm of rain creates a minor swell or a dangerous crest surge.

Grounded in historical gauge flood events
Hydrograph lag and stage response are calibrated against historical storm sensor hydrographs.

THE INFORMATION STACK

What goes in—and what it helps explain.

Availability is stated per input. AtmosGrid never converts a missing parcel observation into a made-up field value.

INFORMATIONSOURCEHOW IT IS USEDSTATUS

01Current river stage (meters)In-situ river level gaugeStarting baseline water level at target sensor.REQUIRED

02Upstream rainfall (3h & 6h mm)Catchment Rainfall APIPrecipitation volume across tributary polygons.REQUIRED

03Antecedent soil saturation (%)AtmosGrid GFS 0–10cm soil moistureDetermines the infiltration vs runoff fraction.REQUIRED

04Historical sensor stage archiveRiver authority telemetry recordsCalibrates unit hydrograph response and lag time.REQUIRED FOR FULL CALIBRATION

A PRACTICAL WORKFLOW

From input to reviewable decision.

The workflow keeps model context, field evidence and human approval in their proper places.

01
Query current gauge stage & soil moisture
Obtain current river level telemetry and antecedent soil moisture saturation index.
02
Aggregate upstream tributary rainfall
Feed rolling 3h and 6h rainfall totals from the Catchment Rainfall API into the response model.
03
Compute calibrated hydrograph surge
Simulate stage delta, time-to-peak lag hours, and 90% confidence uncertainty envelope.
04
Evaluate alert thresholds & actions
Classify response against advisory, warning, and severe flood stage limits with tributary attribution.

HOW INFORMATION BECOMES USEFUL

Examples of decisions it can inform.

These are screening patterns, not automatic instructions. Operational thresholds and local advisories remain authoritative.

SCENARIO 01

Intense upstream rain when soil saturation exceeds 85%

Signal: Model predicts +1.85m surge [uncertainty: 1.55m – 2.15m], reaching warning threshold in 4.5 hours.
Useful action: Deploy temporary flood barriers and close pedestrian riverside gates immediately.
Check before acting: High soil saturation eliminates ground absorption buffer; surge will arrive rapidly with little dampening.

SCENARIO 02

Heavy rain over dry catchment soils in late summer

Signal: 35 mm rain forecast, but soil saturation is only 28%; surge delta modeled at just +0.45m.
Useful action: Maintain standard monitoring posture; avoid unnecessary siren activations or evacuation alerts.
Check before acting: Monitor for hydrophobic crust runoff if rainfall intensity exceeds 20 mm/hr.

SCENARIO 03

New catchment sensor with fewer than 5 historical events

Signal: Uncertainty band is wide (+/- 35%); calibration tier flagged as "screening_model_preliminary".
Useful action: Use result for internal situational screening; require ground gauge confirmation before sounding sirens.
Check before acting: Model becomes fully calibrated once 10+ historical storm hydrographs are ingested.

FOR PRODUCT TEAMS

A transparent API contract.

The response exposes gaps and limitations so an application can explain confidence instead of hiding it.

POST/api/v1/hydrology/basin/river-response

Example request

{
  "sensor_id": "gauge-us-01",
  "catchment_id": "basin-wye-severn-upper",
  "current_stage_m": 2.15,
  "upstream_rainfall_3h_mm": 18.5,
  "upstream_rainfall_6h_mm": 32.0,
  "soil_saturation_pct": 78,
  "historical_events_calibrated": 18
}

JSONdecision response

Example response

{
  "sensor_id": "gauge-us-01",
  "catchment_id": "basin-wye-severn-upper",
  "calibration_status": {
    "historical_sensor_events_used": 18,
    "calibration_tier": "fully_calibrated"
  },
  "current_state": {
    "measured_stage_m": 2.15,
    "soil_saturation_pct": 78,
    "antecedent_moisture_classification": "wet"
  },
  "surge_forecast": {
    "estimated_crest_stage_m": 3.42,
    "crest_90pct_uncertainty_interval_m": [3.18, 3.66],
    "expected_stage_delta_m": 1.27,
    "time_to_peak_hours": 5.2,
    "alert_classification": "warning"
  },
  "tributary_surge_attribution": [
    { "tributary": "South Branch Ridge", "contribution_pct": 46, "status": "surging_fast_runoff" },
    { "tributary": "Upper Gorge Headwaters", "contribution_pct": 34, "status": "elevated_inflow" }
  ],
  "decision_recommendation": {
    "siren_activation_readiness": "standby_crews_active",
    "action": "Issue downstream flood advisory and prepare sluice gate diversion."
  }
}

CAPABILITY BOUNDARIES

Useful now. Honest about what comes next.

Supported now

Calibrated surge stage delta and predicted crest height in meters
Time-to-peak lag calculation (hours to crest arrival)
Rigorous 90% confidence uncertainty envelope [min, max]
Tributary surge attribution (% contribution per upstream fork)
Antecedent soil moisture saturation integration

Additional data required

Historical sensor records for target gauge (at least 10 storm hydrographs for full calibration)
Riverbed rating curve or cross-sectional survey for discharge (m³/s) estimation

BUILD RESPONSIBLY

Use the result to focus attention—not replace field judgment.

Pair AtmosGrid’s regional weather context with local measurements, crop stage, variety guidance and qualified agricultural advice.

Read the API documentation ↗Open the India viewer ↗Explore all basin intelligence modules ↗