River Gauges

URL Path

https://data.api.xweather.com/rivers/gauges/

Data Coverage

Continental US, Alaska, Hawaii

Update Interval

N/A

Time Range

N/A

The rivers/gauges endpoint provides access to enhanced information for the river and lake gauges utilized within the rivers. The primary source for our gauge information is the NOAA Advanced Hydrologic Prediction Service (AHPS). Gauge information will include location information, and when available, recent crests, historical crests, and flood impacts.

Requests

Every request to the endpoint must include one of the supported actions in the url.

https://data.api.xweather.com/rivers/gauges/{action}?client_id={client_id}&client_secret={client_secret}&{params}

Supported Actions

The following actions are supported with the /rivers/gauges endpoint:

Action	Description
:id	Type: stringTypically used for passing a geographical location name or identifier such as city name, lat/long, or even US and Canadian postal codes. Learn more.
closest	Type: stringBased on a location search, the results will be returned in order from closest to farthest. Learn more.
search	Type: stringA generalized action that is determined with the endpoints query parameters. Learn more.
within	Type: stringUses a circle or polygon, define an area to search for results. Learn more.

Response

The following is an example of what each object in the response will consist of. Depending on your requested action, the response may contain multiple instances of this object within an array.

Properties

id (string)

Gauge ID

loc (object)

The location of the record.

loc.long (number)

The place or nearest place to the record.

loc.lat (number)

The latitude coordinate of the record.

place (object)

Object containing information about the place or nearest place to the record.

place.name (string)

The place or nearest place to the record.

place.state (string)

The state abbreviation in which the response is located. This may be null or an empty string depending on the country.

place.country (string)

The 2 letter ISO-3166 country abbreviation in which the response is located.

profile (object)

Object containing information about the location or event.

profile.tz (string)

Timezone name of the location, such as America/New_York.

profile.waterbody (string)

The waterbody that the gauge is on.

profile.cats (object)

Object of the gauge flood categories

profile.cats.actionFT (number)

The height of the action flood category in feet.

profile.cats.actionM (number)

The height of the action flood category in meters.

profile.cats.floodFT (number)

The height of the flood flood category in feet.

profile.cats.floodM (number)

The height of the flood flood category in meters.

profile.cats.moderateFT (number)

The height of the moderate flood category in feet.

profile.cats.moderateM (number)

The height of the moderate flood category in meters.

profile.cats.majorFT (number)

The height of the major flood category in feet.

profile.cats.majorM (number)

The height of the major flood category in meters.

profile.cats.lowthreshM (number)

The height, in feet, that the water body is considered to be low. Null if not defined

profile.cats.lowthreshFT (number)

The height, in meters, that the water body is considered to be low. Null if not defined

profile.impacts (array)

Array of flood impacts. Null if not available

profile.impacts.#.heightFT (number)

The height in feet that the impact begins to occur.

profile.impacts.#.heightM (number)

The height in meters that the impact begins to occur.

profile.impacts.#.text (string)

The text describing the impact.

profile.lowWaterRecords (array)

Array of low water records. Null if not available

profile.lowWaterRecords.#.heightFT (number)

The water height in feet of the low water record.

profile.lowWaterRecords.#.heightM (number)

The water height in meters of the low water record.

profile.lowWaterRecords.#.timestamp (number)

The unix timestamp of the date the low water record occurred

profile.lowWaterRecords.#.dateTimeISO (string)

The ISO-8601 date of the low water record

profile.crests (object)

Object of crest information

profile.crests.recent (array)

Array of recent crests. Null if unavailable

profile.crests.recent.#.heightFT (number)

The height in feet of the crest.

profile.crests.recent.#.heightM (number)

The height in meters of the crest.

profile.crests.recent.#.timestamp (number)

The unix timestamp of the date the crest occurred

profile.crests.recent.#.dateTimeISO (string)

The ISO-8601 date of the crest

profile.crests.historic (array)

Array of historic crests. Null if unavailable

profile.crests.historic.#.heightFT (number)

The height in feet of the crest.

profile.crests.historic.#.heightM (number)

The height in meters of the crest.

profile.crests.historic.#.timestamp (number)

The unix timestamp of the date the crest occurred

profile.crests.historic.#.dateTimeISO (string)

The ISO-8601 date of the crest

relativeTo (object)

Object containing information about the location used for the request compared to the record"s actual location.

relativeTo.lat (number)

Latitude coordinate of the location used for the request. This may be different than the record"s loc.lat value if there was no record exactly at the request location.

relativeTo.long (number)

Longitude coordinate of the location used for the request. This may be different than the record"s loc.long value if there was no record exactly at the request location.

relativeTo.bearing (number)

Bearing in degrees of the record"s location relative to the location used for the request.

relativeTo.bearingENG (string)

Cardinal direction of the record relative to the location used for the request.

relativeTo.distanceKM (number)

Distance, in kilometers, from the requested location to the record"s actual location.

relativeTo.distanceMI (number)

Distance, in miles, from the requested location to the record"s actual location.

[
  {
    "id": "MSPM5",
    "loc": {
      "long": -93.2794,
      "lat": 45.0433
    },
    "place": {
      "name": "fridley abv 37th ave ne",
      "state": "mn",
      "country": "us"
    },
    "profile": {
      "tz": "America/Chicago",
      "waterbody": "mississippi river",
      "cats": {
        "actionFT": 14,
        "actionM": 4.27,
        "floodFT": 16,
        "floodM": 4.88,
        "moderateFT": 16.5,
        "moderateM": 5.03,
        "majorFT": 17,
        "majorM": 5.18,
        "lowthreshM": null,
        "lowthreshFT": null
      },
      "impacts": [
        {
          "heightFT": 18,
          "heightM": 5.49,
          "text": "Water begins to impact water plant."
        },
        {
          "heightFT": 17,
          "heightM": 5.18,
          "text": "Water begins to encroach on roads along the East Bank."
        },
        {
          "heightFT": 16,
          "heightM": 4.88,
          "text": "Temporary measure activities initiated at water facility."
        },
        {
          "heightFT": 15,
          "heightM": 4.57,
          "text": "Minor flooding begins in some industrial and residential areas of north Minneapolis."
        },
        {
          "heightFT": 7.7,
          "heightM": 2.35,
          "text": "River gates closed at water plant."
        }
      ],
      "lowWaterRecords": [
        {
          "heightFT": 2.4,
          "heightM": 0.73,
          "timestamp": 210686400,
          "dateTimeISO": "1976-09-04T07:00:00-05:00"
        },
        {
          "heightFT": 2.7,
          "heightM": 0.82,
          "timestamp": 19137600,
          "dateTimeISO": "1970-08-10T07:00:00-05:00"
        },
        {
          "heightFT": 3,
          "heightM": 0.91,
          "timestamp": -298036800,
          "dateTimeISO": "1960-07-22T07:00:00-05:00"
        }
      ],
      "crests": {
        "recent": [
          {
            "heightFT": 10,
            "heightM": 3.05,
            "timestamp": 1432900800,
            "dateTimeISO": "2015-05-29T07:00:00-05:00"
          },
          {
            "heightFT": 13.5,
            "heightM": 4.11,
            "timestamp": 1403524800,
            "dateTimeISO": "2014-06-23T07:00:00-05:00"
          },
          {
            "heightFT": 12.7,
            "heightM": 3.87,
            "timestamp": 1338552000,
            "dateTimeISO": "2012-06-01T07:00:00-05:00"
          },
          {
            "heightFT": 13.5,
            "heightM": 4.11,
            "timestamp": 1302436800,
            "dateTimeISO": "2011-04-10T07:00:00-05:00"
          },
          {
            "heightFT": 16.4,
            "heightM": 5,
            "timestamp": 988459200,
            "dateTimeISO": "2001-04-28T07:00:00-05:00"
          },
          {
            "heightFT": 16.6,
            "heightM": 5.06,
            "timestamp": 987336000,
            "dateTimeISO": "2001-04-15T07:00:00-05:00"
          },
          {
            "heightFT": 17.1,
            "heightM": 5.21,
            "timestamp": 860673600,
            "dateTimeISO": "1997-04-10T07:00:00-05:00"
          },
          {
            "heightFT": 17.5,
            "heightM": 5.33,
            "timestamp": -22593600,
            "dateTimeISO": "1969-04-14T06:00:00-06:00"
          },
          {
            "heightFT": 20,
            "heightM": 6.1,
            "timestamp": -148564800,
            "dateTimeISO": "1965-04-17T06:00:00-06:00"
          },
          {
            "heightFT": 19.5,
            "heightM": 5.94,
            "timestamp": -559051200,
            "dateTimeISO": "1952-04-14T06:00:00-06:00"
          },
          {
            "heightFT": 16.1,
            "heightM": 4.91,
            "timestamp": -619876800,
            "dateTimeISO": "1950-05-11T07:00:00-05:00"
          },
          {
            "heightFT": 19.2,
            "heightM": 5.85,
            "timestamp": -782308800,
            "dateTimeISO": "1945-03-18T07:00:00-05:00"
          },
          {
            "heightFT": 17,
            "heightM": 5.18,
            "timestamp": -843739200,
            "dateTimeISO": "1943-04-07T07:00:00-05:00"
          }
        ],
        "historic": [
          {
            "heightFT": 20,
            "heightM": 6.1,
            "timestamp": -148564800,
            "dateTimeISO": "1965-04-17T06:00:00-06:00"
          },
          {
            "heightFT": 19.5,
            "heightM": 5.94,
            "timestamp": -559051200,
            "dateTimeISO": "1952-04-14T06:00:00-06:00"
          },
          {
            "heightFT": 19.2,
            "heightM": 5.85,
            "timestamp": -782308800,
            "dateTimeISO": "1945-03-18T07:00:00-05:00"
          },
          {
            "heightFT": 17.5,
            "heightM": 5.33,
            "timestamp": -22593600,
            "dateTimeISO": "1969-04-14T06:00:00-06:00"
          },
          {
            "heightFT": 17.1,
            "heightM": 5.21,
            "timestamp": 860673600,
            "dateTimeISO": "1997-04-10T07:00:00-05:00"
          },
          {
            "heightFT": 17,
            "heightM": 5.18,
            "timestamp": -843739200,
            "dateTimeISO": "1943-04-07T07:00:00-05:00"
          },
          {
            "heightFT": 16.6,
            "heightM": 5.06,
            "timestamp": 987336000,
            "dateTimeISO": "2001-04-15T07:00:00-05:00"
          },
          {
            "heightFT": 16.4,
            "heightM": 5,
            "timestamp": 988459200,
            "dateTimeISO": "2001-04-28T07:00:00-05:00"
          },
          {
            "heightFT": 16.1,
            "heightM": 4.91,
            "timestamp": -619876800,
            "dateTimeISO": "1950-05-11T07:00:00-05:00"
          },
          {
            "heightFT": 13.5,
            "heightM": 4.11,
            "timestamp": 1302436800,
            "dateTimeISO": "2011-04-10T07:00:00-05:00"
          },
          {
            "heightFT": 13.5,
            "heightM": 4.11,
            "timestamp": 1403524800,
            "dateTimeISO": "2014-06-23T07:00:00-05:00"
          },
          {
            "heightFT": 12.7,
            "heightM": 3.87,
            "timestamp": 1338552000,
            "dateTimeISO": "2012-06-01T07:00:00-05:00"
          },
          {
            "heightFT": 10,
            "heightM": 3.05,
            "timestamp": 1432900800,
            "dateTimeISO": "2015-05-29T07:00:00-05:00"
          }
        ]
      }
    },
    "relativeTo": {
      "lat": 44.97997,
      "long": -93.26384,
      "bearing": 350,
      "bearingENG": "N",
      "distanceKM": 7.147,
      "distanceMI": 4.441
    }
  }
]

Endpoints