# National Water Prediction Service

> Watch rivers across the US with the National Weather Service's river gauges: list the gauges in a state that are flooding or forecast to flood, read a gauge's latest level, forecast, flood stages and what floods at each level, see past crests and the gauges up and down the river, get the National Water Model's streamflow forecasts, and run a workflow when a gauge reaches a flood category. No account or API key required.

App · 9 actions. Web page: https://docs.lodol.com/docs/integrations/noaa-nwps

## Actions

### Get flood crests

Get the highest crests on record at a gauge, or its most recent ones, with the day, the stage, the flow when measured and the flood category each reached.

**Inputs**

- Gauge (`gauge`, text, required): The gauge's ID, e.g. PTTP1 for the Ohio River at Pittsburgh, its USGS site number, or the address of its page on water.noaa.gov.
- Crests (`crest_type`, text): The highest on record, or the most recent. Defaults to the highest. One of: `historic` (Highest on record), `recent` (Most recent). Default: `historic`.
- Most crests (`limit`, number): The most crests to list, from 1 to 500. Defaults to 10. From 1 to 500. Default: `10`.

**Outputs**

- `count` (number): How many crests are listed.
- `crest_type` (text): 'historic' for the highest crests on record, highest first, or 'recent' for the latest, newest first.
- `crests` (list): The crests.
- `flow_unit` (text): The unit of the crests' flows, e.g. 'cfs'.
- `lid` (text): The gauge's NWS location ID, e.g. 'PTTP1'.
- `name` (text): The gauge's name.
- `stage_unit` (text): The unit of stages, usually 'ft' (feet).
- `summary` (text): One or two sentences saying what came back.
- `total` (number): How many crests of this kind NOAA has.

**Example output**

```json
{
  "count": 3,
  "crest_type": "historic",
  "crests": [
    {
      "date": "1936-03-18",
      "flood_category": "major",
      "flood_category_label": "Major flooding",
      "flow": null,
      "occurred_at": "1936-03-18T00:00:00Z",
      "stage": 46
    },
    {
      "date": "1907-03-15",
      "flood_category": "major",
      "flood_category_label": "Major flooding",
      "flow": null,
      "occurred_at": "1907-03-15T00:00:00Z",
      "stage": 38.5
    },
    {
      "date": "1942-12-31",
      "flood_category": "major",
      "flood_category_label": "Major flooding",
      "flow": null,
      "occurred_at": "1942-12-31T00:00:00Z",
      "stage": 36.6
    }
  ],
  "flow_unit": "cfs",
  "lid": "PTTP1",
  "name": "Ohio River at Pittsburgh",
  "stage_unit": "ft",
  "summary": "3 of 3 historic crests for Ohio River at Pittsburgh (PTTP1), highest first; the first is 46 ft on 1936-03-18.",
  "total": 3
}
```

### Get flood impacts

Get what happens at each river level at a gauge, in NOAA's words (which roads, homes and places flood), the highest first, and which of them the latest reading and the forecast reach.

**Inputs**

- Gauge (`gauge`, text, required): The gauge's ID, e.g. PTTP1 for the Ohio River at Pittsburgh, its USGS site number, or the address of its page on water.noaa.gov.

**Outputs**

- `count` (number): How many impacts NOAA lists.
- `current_impact` (text): What happens at the latest reading's stage: the statement for the highest impact it reaches, if any.
- `forecast_impact` (text): The statement for the highest impact the forecast reaches, if any.
- `forecast_stage` (number): The forecast stage NOAA flags for the gauge.
- `impacts` (list): What happens as the river rises, the highest stage first.
- `lid` (text): The gauge's NWS location ID, e.g. 'PTTP1'.
- `name` (text): The gauge's name.
- `observed_stage` (number): The latest reading's stage.
- `stage_unit` (text): The unit of stages, usually 'ft' (feet).
- `summary` (text): One or two sentences saying what came back.

**Example output**

```json
{
  "count": 3,
  "current_impact": null,
  "forecast_impact": null,
  "forecast_stage": 17.4,
  "impacts": [
    {
      "flood_category": "major",
      "flood_category_label": "Major flooding",
      "reached_in_forecast": false,
      "reached_now": false,
      "stage": 46,
      "statement": "Severe damage occurs in Pittsburgh with up to 15 feet of water in the golden triangle. This is the level of the record flood in march of 1936."
    },
    {
      "flood_category": "major",
      "flood_category_label": "Major flooding",
      "reached_in_forecast": false,
      "reached_now": false,
      "stage": 40,
      "statement": "PNC Park is flooded along Federal Street."
    },
    {
      "flood_category": "minor",
      "flood_category_label": "Minor flooding",
      "reached_in_forecast": false,
      "reached_now": false,
      "stage": 22,
      "statement": "The Tenth Street Bypass floods."
    }
  ],
  "lid": "PTTP1",
  "name": "Ohio River at Pittsburgh",
  "observed_stage": 17.15,
  "stage_unit": "ft",
  "summary": "3 flood impacts for Ohio River at Pittsburgh (PTTP1); none reached at the latest reading."
}
```

### Get gauge

Get one river gauge: where it is, the stages at which flooding begins (action, minor, moderate and major), its latest reading and forecast with their flood category, its highest crest on record, and its page and hydrograph on water.noaa.gov.

**Inputs**

- Gauge (`gauge`, text, required): The gauge's ID, e.g. PTTP1 for the Ohio River at Pittsburgh, its USGS site number, or the address of its page on water.noaa.gov.

**Outputs**

- `county` (text): The county the gauge is in.
- `description` (text): NOAA's note about where the gauge is.
- `downstream_lid` (text): The ID of the next gauge downstream.
- `flood_impact_count` (number): How many flood impacts NOAA lists for the gauge (see Get flood impacts).
- `flood_stages` (object): The stage (and flow) at which each flood category begins.
- `flow_unit` (text): The unit of the flood stages' flows, e.g. 'cfs'.
- `forecast` (object): The forecast NOAA flags for the gauge, usually its highest forecast point, and its flood category. Most gauges have no forecast.
- `forecast_reliability` (text): NOAA's note on how often it forecasts the gauge.
- `highest_crest` (object): The highest crest on record.
- `hydrograph_url` (text): A picture of the gauge's recent readings and forecast against its flood stages.
- `in_service` (true/false): False when NOAA has taken the gauge out of service.
- `latitude` (number): The gauge's latitude.
- `lid` (text): The gauge's NWS location ID, e.g. 'PTTP1'.
- `longitude` (number): The gauge's longitude.
- `name` (text): The gauge's name, e.g. 'Ohio River at Pittsburgh'.
- `nws_office` (text): Where the local NWS office responsible for the gauge is, e.g. 'Moon Township'.
- `nws_office_id` (text): The local NWS office's code, e.g. 'PBZ'.
- `observed` (object): The gauge's latest reading and its flood category.
- `page_url` (text): The gauge's page on water.noaa.gov.
- `reach_id` (text): The National Water Model reach the gauge is on, for Get reach and Get streamflow.
- `river_forecast_center` (text): The NWS river forecast center that forecasts the gauge, e.g. 'Ohio River Forecast Center'.
- `service_note` (text): NOAA's note on why the gauge is out of service.
- `stage_unit` (text): The unit of stages, usually 'ft' (feet).
- `state` (text): The two-letter code of the gauge's state, e.g. 'PA'.
- `state_name` (text): The gauge's state, e.g. 'Pennsylvania'.
- `summary` (text): One or two sentences saying what came back.
- `time_zone` (text): The gauge's time zone, e.g. 'EST5EDT'.
- `upstream_lid` (text): The ID of the next gauge upstream.
- `usgs_id` (text): The USGS site number of the gauge, when it has one.

**Example output**

```json
{
  "county": "Allegheny",
  "description": null,
  "downstream_lid": "EMXP1",
  "flood_impact_count": 3,
  "flood_stages": {
    "action": {
      "flow": null,
      "stage": 18
    },
    "major": {
      "flow": null,
      "stage": 28
    },
    "minor": {
      "flow": null,
      "stage": 22
    },
    "moderate": {
      "flow": null,
      "stage": 25
    }
  },
  "flow_unit": "cfs",
  "forecast": {
    "at": "2026-11-03T06:00:00Z",
    "flood_category": "no_flooding",
    "flood_category_label": "No flooding",
    "flow": 103,
    "flow_unit": "kcfs",
    "stage": 17.4,
    "stage_unit": "ft"
  },
  "forecast_reliability": "Forecasts are issued routinely year-round.",
  "highest_crest": {
    "date": "1936-03-18",
    "flood_category": "major",
    "flood_category_label": "Major flooding",
    "flow": null,
    "occurred_at": "1936-03-18T00:00:00Z",
    "stage": 46
  },
  "hydrograph_url": "https://water.noaa.gov/resources/hydrographs/pttp1_hg.png",
  "in_service": true,
  "latitude": 40.439444444444,
  "lid": "PTTP1",
  "longitude": -80.010833333333,
  "name": "Ohio River at Pittsburgh",
  "nws_office": "Moon Township",
  "nws_office_id": "PBZ",
  "observed": {
    "at": "2026-11-02T19:00:00Z",
    "flood_category": "no_flooding",
    "flood_category_label": "No flooding",
    "flow": 101,
    "flow_unit": "kcfs",
    "stage": 17.15,
    "stage_unit": "ft"
  },
  "page_url": "https://water.noaa.gov/gauges/pttp1",
  "reach_id": "3786893",
  "river_forecast_center": "Ohio River Forecast Center",
  "service_note": null,
  "stage_unit": "ft",
  "state": "PA",
  "state_name": "Pennsylvania",
  "summary": "Ohio River at Pittsburgh (PTTP1), PA: 17.15 ft at 2026-11-02T19:00:00Z: no flooding; forecast 17.4 ft at 2026-11-03T06:00:00Z: no flooding. Flood stage 22 ft.",
  "time_zone": "EST5EDT",
  "upstream_lid": "BDDP1",
  "usgs_id": "03085152"
}
```

### Get rating table

Get a gauge's rating table: the flow the river carries at each stage, which NOAA uses to turn a river level into a flow.

**Inputs**

- Gauge (`gauge`, text, required): The gauge's ID, e.g. PTTP1 for the Ohio River at Pittsburgh, its USGS site number, or the address of its page on water.noaa.gov.
- Most rows (`limit`, number): The most rows to list, from 1 to 10000. Defaults to 100. From 1 to 10000. Default: `100`.
- Order (`order`, text): Lowest stage first, or highest first. Defaults to lowest. One of: `lowest_first` (Lowest stage first), `highest_first` (Highest stage first). Default: `lowest_first`.
- Tenths of a foot only (`tenths_only`, true/false): Only stages in steps of a tenth of a foot, for a shorter table. Default: `false`.

**Outputs**

- `count` (number): How many rows are listed.
- `flow_unit` (text): The unit of the flows, e.g. 'cfs'.
- `lid` (text): The gauge's NWS location ID, e.g. 'PTTP1'.
- `ratings` (list): The rows of the table.
- `stage_unit` (text): The unit of stages, usually 'ft' (feet).
- `summary` (text): One or two sentences saying what came back.

**Example output**

```json
{
  "count": 3,
  "flow_unit": "cfs",
  "lid": "PTTP1",
  "ratings": [
    {
      "flow": 0,
      "stage": 16.3
    },
    {
      "flow": 500,
      "stage": 16.4
    },
    {
      "flow": 2000,
      "stage": 16.5
    }
  ],
  "stage_unit": "ft",
  "summary": "3 rows of gauge PTTP1's rating table, from 16.3 ft (0 cfs) to 16.5 ft (2,000 cfs)."
}
```

### Get reach

Get a stretch of river in the National Water Model: its river, where it is, the reaches flowing into and out of it, and which streamflow forecasts it has.

**Inputs**

- Reach (`reach`, text, required): The National Water Model's ID for a stretch of river, e.g. 3786893, or a gauge's ID (PTTP1) to use the stretch the gauge is on.

**Outputs**

- `downstream_reaches` (list): The reaches it flows on to.
- `gauge_lid` (text): The gauge the reach was found from, when a gauge was given.
- `latitude` (number): The reach's latitude.
- `longitude` (number): The reach's longitude.
- `name` (text): The river the reach is on.
- `reach_id` (text): The reach's ID in the National Water Model.
- `streamflow_series` (list): The streamflow Get streamflow can give for the reach: analysis_assimilation, short_range, medium_range or medium_range_blend.
- `summary` (text): One or two sentences saying what came back.
- `upstream_reaches` (list): The reaches that flow into it.

**Example output**

```json
{
  "downstream_reaches": [
    {
      "reach_id": "3786927",
      "stream_order": "7"
    }
  ],
  "gauge_lid": null,
  "latitude": 40.437,
  "longitude": -80.0065,
  "name": "Monongahela River",
  "reach_id": "3786893",
  "streamflow_series": [
    "analysis_assimilation",
    "short_range",
    "medium_range",
    "medium_range_blend"
  ],
  "summary": "Reach 3786893 (Monongahela River): 1 reach flows into it and 1 out of it; streamflow: recent past (analysis), next 18 hours, next 10 days (average of the runs), next 10 days (blended).",
  "upstream_reaches": [
    {
      "reach_id": "3785853",
      "stream_order": "7"
    }
  ]
}
```

### Get stage and flow

Get a gauge's readings of the river's height (stage) and flow over the past hours, its forecast, or both, with the latest and highest of each.

**Inputs**

- Gauge (`gauge`, text, required): The gauge's ID, e.g. PTTP1 for the Ohio River at Pittsburgh, its USGS site number, or the address of its page on water.noaa.gov.
- Readings (`readings`, text): The past readings, the forecast, or both. Defaults to both. One of: `both` (Past readings and the forecast), `observed` (Past readings), `forecast` (The forecast). Default: `both`.
- Hours of readings (`hours`, number): How many hours of past readings to return, counting back from the latest, from 1 to 720 (30 days). Defaults to 24. From 1 to 720. Default: `24`.

**Outputs**

- `forecast` (object): The gauge's forecast. Empty when NOAA doesn't forecast the gauge now, or only readings were asked for.
- `lid` (text): The gauge's NWS location ID, e.g. 'PTTP1'.
- `observed` (object): The gauge's readings over the hours asked for. Empty when only the forecast was asked for.
- `summary` (text): One or two sentences saying what came back.

**Example output**

```json
{
  "forecast": {
    "count": 3,
    "flow_unit": "kcfs",
    "highest": {
      "at": "2026-11-03T06:00:00Z",
      "flow": 103,
      "stage": 17.4
    },
    "issued_at": "2026-11-02T14:41:00Z",
    "latest": {
      "at": "2026-11-03T06:00:00Z",
      "flow": 103,
      "stage": 17.4
    },
    "readings": [
      {
        "at": "2026-11-02T18:00:00Z",
        "flow": 102,
        "stage": 17.3
      },
      {
        "at": "2026-11-03T00:00:00Z",
        "flow": 102,
        "stage": 17.3
      },
      {
        "at": "2026-11-03T06:00:00Z",
        "flow": 103,
        "stage": 17.4
      }
    ],
    "stage_name": "Stage",
    "stage_unit": "ft"
  },
  "lid": "PTTP1",
  "observed": {
    "count": 3,
    "flow_unit": "kcfs",
    "highest": {
      "at": "2026-11-02T18:50:00Z",
      "flow": 101,
      "stage": 17.16
    },
    "issued_at": "2026-11-02T19:00:00Z",
    "latest": {
      "at": "2026-11-02T19:00:00Z",
      "flow": 101,
      "stage": 17.15
    },
    "readings": [
      {
        "at": "2026-11-02T18:50:00Z",
        "flow": 101,
        "stage": 17.16
      },
      {
        "at": "2026-11-02T18:55:00Z",
        "flow": 101,
        "stage": 17.16
      },
      {
        "at": "2026-11-02T19:00:00Z",
        "flow": 101,
        "stage": 17.15
      }
    ],
    "stage_name": "Stage",
    "stage_unit": "ft"
  },
  "summary": "Gauge PTTP1: 3 readings in the last 24 hours, latest 17.15 ft at 2026-11-02T19:00:00Z; 3 forecast points, highest 17.4 ft at 2026-11-03T06:00:00Z."
}
```

### Get streamflow

Get the National Water Model's streamflow for a stretch of river, hour by hour: the recent past, the next 18 hours or the next 10 days, with the highest flow and when. It covers rivers with no gauge too.

**Inputs**

- Reach (`reach`, text, required): The National Water Model's ID for a stretch of river, e.g. 3786893, or a gauge's ID (PTTP1) to use the stretch the gauge is on.
- Streamflow (`series`, text): Which streamflow to get. Defaults to the next 18 hours. One of: `analysis_assimilation` (Recent past (analysis)), `short_range` (Next 18 hours), `medium_range` (Next 10 days (average of the runs)), `medium_range_blend` (Next 10 days (blended)). Default: `short_range`.

**Outputs**

- `count` (number): How many values there are.
- `flow_unit` (text): The unit of the flows, 'ft³/s' (cubic feet per second).
- `flows` (list): The streamflow, hour by hour, oldest first.
- `gauge_lid` (text): The gauge the reach was found from, when a gauge was given.
- `model_run_at` (text): When the model run behind these values started (ISO 8601, UTC).
- `name` (text): The river the reach is on.
- `peak` (object): The highest flow and when.
- `reach_id` (text): The reach's ID in the National Water Model.
- `series` (text): Which streamflow: analysis_assimilation, short_range, medium_range or medium_range_blend.
- `series_label` (text): The streamflow in words, e.g. 'Next 18 hours'.
- `summary` (text): One or two sentences saying what came back.

**Example output**

```json
{
  "count": 3,
  "flow_unit": "ft\u00b3/s",
  "flows": [
    {
      "at": "2026-11-02T18:00:00Z",
      "flow": 5537.69
    },
    {
      "at": "2026-11-02T19:00:00Z",
      "flow": 5512.62
    },
    {
      "at": "2026-11-02T20:00:00Z",
      "flow": 5487.9
    }
  ],
  "gauge_lid": null,
  "model_run_at": "2026-11-02T17:00:00Z",
  "name": "Monongahela River",
  "peak": {
    "at": "2026-11-02T18:00:00Z",
    "flow": 5537.69
  },
  "reach_id": "3786893",
  "series": "short_range",
  "series_label": "Next 18 hours",
  "summary": "Next 18 hours for reach 3786893 (Monongahela River): 3 values, highest 5,538 ft\u00b3/s at 2026-11-02T18:00:00Z."
}
```

### Get upstream and downstream gauges

List the gauges upstream and downstream of a gauge on the same river system, nearest first, to see what is coming and where it goes next.

**Inputs**

- Gauge (`gauge`, text, required): The gauge's ID, e.g. PTTP1 for the Ohio River at Pittsburgh, its USGS site number, or the address of its page on water.noaa.gov.

**Outputs**

- `downstream` (list): The gauges downstream, nearest first.
- `downstream_count` (number): How many gauges are downstream.
- `lid` (text): The gauge's NWS location ID, e.g. 'PTTP1'.
- `name` (text): The gauge's name.
- `summary` (text): One or two sentences saying what came back.
- `upstream` (list): The gauges upstream, nearest first.
- `upstream_count` (number): How many gauges are upstream.

**Example output**

```json
{
  "downstream": [
    {
      "inactive": false,
      "lid": "EMXP1",
      "name": "Ohio River above Emsworth L/d  Pool",
      "page_url": "https://water.noaa.gov/gauges/emxp1"
    },
    {
      "inactive": false,
      "lid": "EMSP1",
      "name": "Ohio River at Emsworth Lock and Dam",
      "page_url": "https://water.noaa.gov/gauges/emsp1"
    }
  ],
  "downstream_count": 2,
  "lid": "PTTP1",
  "name": "Ohio River at Pittsburgh",
  "summary": "2 gauges upstream and 2 downstream of Ohio River at Pittsburgh (PTTP1).",
  "upstream": [
    {
      "inactive": false,
      "lid": "BDDP1",
      "name": "Monongahela River at Braddock Lock and Dam",
      "page_url": "https://water.noaa.gov/gauges/bddp1"
    },
    {
      "inactive": false,
      "lid": "ELZP1",
      "name": "Monongahela River at Elizabeth Lock and Dam",
      "page_url": "https://water.noaa.gov/gauges/elzp1"
    }
  ],
  "upstream_count": 2
}
```

### List gauges

List the river gauges in a state or an area, each with its latest reading and forecast and their flood category. Choose a flood category to list only the gauges flooding or forecast to flood. The most flooded come first.

**Inputs**

- State (`state`, text): The state or territory to list. Leave blank to list an area instead. One of: `AL` (Alabama (AL)), `AK` (Alaska (AK)), `AZ` (Arizona (AZ)), `AR` (Arkansas (AR)), `CA` (California (CA)), `CO` (Colorado (CO)), `CT` (Connecticut (CT)), `DE` (Delaware (DE)), `DC` (District of Columbia (DC)), `FL` (Florida (FL)), and 43 more.
- West edge (`west`, number): For an area: its western longitude, e.g. -80.2. Fill in all four edges, or none. From -180 to 180.
- South edge (`south`, number): For an area: its southern latitude, e.g. 40.3. From -90 to 90.
- East edge (`east`, number): For an area: its eastern longitude, e.g. -79.8. From -180 to 180.
- North edge (`north`, number): For an area: its northern latitude, e.g. 40.6. From -90 to 90.
- Name contains (`name_contains`, text): Only gauges whose name contains this text, e.g. Ohio River. Leave blank for every gauge.
- Flooding at least (`flood_category`, text): Only gauges at or above this flood category. Leave blank for every gauge. One of: `action` (Near flooding (action stage) or worse), `minor` (Minor flooding or worse), `moderate` (Moderate flooding or worse), `major` (Major flooding).
- Flooding in (`reading`, text): Whether the flood category is read from the latest reading, the forecast, or either. Defaults to either. One of: `either` (The latest reading or the forecast), `observed` (The latest reading), `forecast` (The forecast). Default: `either`.
- Most gauges (`limit`, number): The most gauges to list, from 1 to 1000. Defaults to 100. From 1 to 1000. Default: `100`.

**Outputs**

- `count` (number): How many gauges are in this answer.
- `gauges` (list): The gauges, the most flooded first, then by name.
- `has_more` (true/false): True when more gauges matched than are listed.
- `summary` (text): One or two sentences saying what came back.
- `total` (number): How many gauges matched, before the most to list was applied.

**Example output**

```json
{
  "count": 2,
  "gauges": [
    {
      "forecast": {
        "at": null,
        "flood_category": "fcst_not_current",
        "flood_category_label": "No current forecast",
        "flow": null,
        "flow_unit": null,
        "stage": null,
        "stage_unit": null
      },
      "latitude": 40.505277777778,
      "lid": "EMSP1",
      "longitude": -80.089722222222,
      "name": "Ohio River at Emsworth Lock and Dam",
      "nws_office": "Moon Township",
      "nws_office_id": "PBZ",
      "observed": {
        "at": "2026-11-02T18:00:00Z",
        "flood_category": "not_defined",
        "flood_category_label": "No flood stages set",
        "flow": 12.9,
        "flow_unit": "kcfs",
        "stage": 14,
        "stage_unit": "ft"
      },
      "page_url": "https://water.noaa.gov/gauges/emsp1",
      "river_forecast_center": "Ohio River Forecast Center",
      "state": "PA",
      "state_name": "Pennsylvania"
    },
    {
      "forecast": {
        "at": "2026-11-03T06:00:00Z",
        "flood_category": "no_flooding",
        "flood_category_label": "No flooding",
        "flow": 103,
        "flow_unit": "kcfs",
        "stage": 17.4,
        "stage_unit": "ft"
      },
      "latitude": 40.439444444444,
      "lid": "PTTP1",
      "longitude": -80.010833333333,
      "name": "Ohio River at Pittsburgh",
      "nws_office": "Moon Township",
      "nws_office_id": "PBZ",
      "observed": {
        "at": "2026-11-02T19:00:00Z",
        "flood_category": "no_flooding",
        "flood_category_label": "No flooding",
        "flow": 101,
        "flow_unit": "kcfs",
        "stage": 17.15,
        "stage_unit": "ft"
      },
      "page_url": "https://water.noaa.gov/gauges/pttp1",
      "river_forecast_center": "Ohio River Forecast Center",
      "state": "PA",
      "state_name": "Pennsylvania"
    }
  ],
  "has_more": false,
  "summary": "Found 2 gauges in the area.",
  "total": 2
}
```
