Feature - add support to retrieve flood stages

[elmerehbi]

I propose to add support for retrieving flood stages from the water service.

The following retrieves all flood stages in a single call:

all_flood_stages = get_flood_stages()

To get the flood stages for a particular site number: get_flood_stage(site_no=["07144100"])

For multiple sites:

stations = ["07144100", "07144101"]
print(get_flood_stage(stations))
{'07144100': {'action_stage': '20', 'flood_stage': '22', 'moderate_flood_stage': '25', 'major_flood_stage': '26'}, '07144101': None}

[thodson-usgs]

Good proposal, but let's call the new module waterwatch and we can include other WaterWatch data.
However, I see a note that WaterWatch is no longer supported.
https://waterwatch.usgs.gov/index.php?id=ww
I'll try the address to see if there's an alternative.

[thodson-usgs]

WaterWatch won't receive any new features but it will continue to operate.

Here are a few of my initial thoughts on how to improve this feature. I'm open to yours

• Let's change the file name to waterwatch.py
• Remove get_flood_stages and instead have get_flood_stage return all sites when passed no options.
• I think users would prefer the json parsed as dataframe. Maybe define add a _read_json() function that returns a dataframe as in the nwis module.

[elmerehbi]

Good points. Will do the requested changes.

My reasoning behind having two separate functions is three-folds: (1) separation of concerns so that the data source can easily be changed in the future without affecting the main function used by the user and (2) also a unit test can be written and (3) giving the user the ability to store all flood stages in memory (e.g. in an interactive environment like a Jupyter notebook) hence reducing the number of HTTP requests needed. What do you think about this? In any case I am happy to change it as per your request.

[elmerehbi]

• Let's change the file name to waterwatch.py
• Remove get_flood_stages and instead have get_flood_stage return all sites when passed no options: I made an argument in the previous reply about why I would keep them separate though I did merge them.
• I think users would prefer the json parsed as dataframe. Maybe define add a _read_json() function that returns a dataframe as in the nwis module: The default output is a pd.DataFrame however I give the user the ability to specify a dict output. We can remove that if you are not happy with it :)

[elmerehbi]

WaterWatch won't receive any new features but it will continue to operate.

Any idea if there's an alternative source? Is this maintained by NOAA nowadays?

[thodson-usgs]

Ah, I assumed waterwatch allowed multi site queries, but looking at the REST API, it seems to only allow one site or all sites:
https://waterwatch.usgs.gov/webservices/