Rivers

Rivers

URL Path
https://api.aerisapi.com/rivers/
Data Coverage
Continental US, Alaska, Hawaii
Update Interval
Hourly
Time Range
N/A

The rivers endpoint provides access to the latest river and lakes gauge observations. The primary source of our gauge observations data is the NOAA Advanced Hydrologic Prediction Service (AHPS). Gauge observations include information on the current water level or flow, flood stages, and low water thresholds.

Requests

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

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

Supported Actions

The following actions are supported with the /rivers endpoint:

ActionDescription
:idType: 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.
closestType: stringBased on a location search, the results will be returned in order from closest to farthest. Learn more.
withinType: stringUses a circle or polygon, define an area to search for results. Learn more.
searchType: stringA generalized action that is determined with the endpoints query parameters. 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)

The river 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.

ob (object)

The observation object

ob.timestamp (number)

Unix timestamp of the observation time

ob.dateTimeISO (string)

The observation time in ISO-8601 format

ob.heightFT (number)

The water height in feet. Null if unavailable

ob.heightM (number)

The water height in meters. Null if unavailable

ob.flowCFS (number)

The water flow in cubic feet per second. Null if unavailable

ob.flowCMS (number)

The water flow in cubic meters per second. Null if unavailable

ob.secondary ()

Secondary sensor for gauges that include backup. Normally null, since most do not include backups

ob.secondary.heightFT (number)

The water height in feet. Null if unavailable

ob.secondary.heightM (number)

The water height in meters. Null if unavailable

ob.secondary.flowCFS (number)

The water flow in cubic feet per second. Null if unavailable

ob.secondary.flowCMS (number)

The water flow in cubic meters per second. Null if unavailable

ob.status (string)

The current river/lake status:

out_of_service - Gauge is known to be out of service
obs_not_current - Gauge has not reported updated observations recently
not_defined - Gauge is reporting observations but has no action/flooding levels defined, thus cannot determine if flooding
low_threshold - Gauge is reporting levels below the defined low water threshold
no_flooding - Gauge is reporting observations and below flood and action levels
action - Gauge is reporting observations at or above action levels. Normally means near flood stage
minor - Gauge is reporting levels at or above the minor flood level
moderate - Gauge is reporting levels at or above the defined moderate flood level
major - Gauge is reporting levels at or above the defined major flood level

ob.statusCode (number)

The numeric code of the river/lake status:

out_of_service: -1
obs_not_current: 0
not_defined: 1
low_threshold: 3
no_flooding: 5
action: 7
minor: 9
moderate: 11
major: 13

ob.impact (string)

Local impacts, if available and river is flooding. Null if unavailable or river is not flooding

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 water body where the gauge is located

profile.cats (object)

When available, the define categories for various flood levels at the gauge location. Null if not defined

profile.cats.actionFT (number)

The height, in feet, when the waterbody nears flood stage

profile.cats.actionM (number)

The height, in meters, when the waterbody nears flood stage

profile.cats.floodFT (number)

The height, in feet, when the waterbody floods

profile.cats.floodM (number)

The height, in meters, when the waterbody floods

profile.cats.moderateFT (number)

The height, in feet, when the waterbody reaches moderate flood stage

profile.cats.moderateM (number)

The height, in meters, when the waterbody reaches moderate flood stage

profile.cats.majorFT (number)

The height, in feet, when the waterbody reaches major flood stage

profile.cats.majorM (number)

The height, in meters, when the waterbody reaches major flood stage

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.hasImpacts (boolean)

True if the gauge include flooding impacts, false if unavailable

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
    },
    "ob": {
      "timestamp": 1702589400,
      "dateTimeISO": "2023-12-14T15:30:00-06:00",
      "heightFT": 4.83,
      "heightM": 1.47,
      "flowCFS": 5110,
      "flowCMS": 144.7,
      "secondary": null,
      "status": "no_flooding",
      "statusCode": 5,
      "impact": null
    },
    "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
      },
      "hasImpacts": true
    },
    "relativeTo": {
      "lat": 44.97997,
      "long": -93.26384,
      "bearing": 350,
      "bearingENG": "N",
      "distanceKM": 7.147,
      "distanceMI": 4.441
    }
  }
]