Skip to content

River: Migrate USGS requests to new QGC Water Data API (issue #467) #472

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
simmsa wants to merge 3 commits into
base: develop
Choose a base branch
from
Draft

River: Migrate USGS requests to new QGC Water Data API (issue #467) #472

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4c6fb6b
River: Migrate USGS requests to new QGC Water Data API (issue #467)
simmsa Oct 26, 2026
ccad3a7
Examples: River, document USGS API Key and timezone options
simmsa Oct 26, 2026
a7d6898
River: Add deprecated use_legacy_api option and USGS parity tests (#467)
simmsa Oct 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions examples/ADCP_Delft3D_TRTS_example.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1808,7 +1808,9 @@
"metadata": {},
"source": [
"### D3D: USGS Water Level\n",
"The United States Geological Survey has a nearby survey station (#15515500) downstream of the TRTS which records discharge and water level. The MHKiT River module has the capability to request data from USGS survey stations as demonstrated in the river example. Using MHKiT's river module the water level for the USGS station was collected for the same day as the ADCP data was collected. The USGS assigns a parameter number of '00065' for water level or Gage height. The water level was averaged to be roughly 2.7m. This number is directly input into the Delft3D model and isn't used in this example notebook. Further examples of using the river module are shown in the `river_example`. Similar to the water level the discharge was found using the same MHKit river module except swapping out the parameter number for '00060' to get the discharge data. The discharge was averaged to be 1789 $m^3/s$. This value was also directly input to the Delft3D model and isn't used in this example notebook."
"The United States Geological Survey has a nearby survey station (#15515500) downstream of the TRTS which records discharge and water level. The MHKiT River module has the capability to request data from USGS survey stations as demonstrated in the river example. Using MHKiT's river module the water level for the USGS station was collected for the same day as the ADCP data was collected. The USGS assigns a parameter number of '00065' for water level or Gage height. The water level was averaged to be roughly 2.7m. This number is directly input into the Delft3D model and isn't used in this example notebook. Further examples of using the river module are shown in the `river_example`. Similar to the water level the discharge was found using the same MHKit river module except swapping out the parameter number for '00060' to get the discharge data. The discharge was averaged to be 1789 $m^3/s$. This value was also directly input to the Delft3D model and isn't used in this example notebook.\n",
"\n",
"Requesting USGS data works best with a free USGS API key set as the `USGS_API_KEY` environment variable (e.g. `os.environ[\"USGS_API_KEY\"] = \"your-api-key\"`); see the `river_example` for more details. The calls below use `\"timezone\": \"America/Anchorage\"` so that the requested day is the local day at the station."
]
},
{
Expand Down Expand Up @@ -1857,7 +1859,7 @@
"# parameter=\"00065\",\n",
"# start_date=\"2010-08-10\",\n",
"# end_date=\"2010-08-10\",\n",
"# options={\"data_type\":\"Instantaneous\"},\n",
"# options={\"data_type\": \"Instantaneous\", \"timezone\": \"America/Anchorage\"},\n",
"# )\n",
"\n",
"# Plot data\n",
Expand All @@ -1875,7 +1877,7 @@
"# parameter=\"00060\",\n",
"# start_date=\"2010-08-10\",\n",
"# end_date=\"2010-08-10\",\n",
"# options={\"data_type\":\"Instantaneous\"},\n",
"# options={\"data_type\": \"Instantaneous\", \"timezone\": \"America/Anchorage\"},\n",
"# )\n",
"\n",
"# Print data\n",
Expand Down
22 changes: 20 additions & 2 deletions examples/river_example.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,26 @@
" \n",
"We will start by requesting daily discharge data from the USGS website for the Tanana River near Nenana, Alaska. The function `request_usgs_data` in the river IO module returns a Pandas DataFrame. The function requires the station number, parameter number, timeframe, and type of data. \n",
"\n",
"The station number can be found on the USGS website, though this is more difficult than searching the web for \"USGS Tanana near Nenana\" which should return a link to https://waterdata.usgs.gov/nwis/inventory/?site_no=15515500. This page contains an overview of the available data, including daily discharge data. \n",
"The station number can be found on the USGS website, though this is more difficult than searching the web for \"USGS Tanana near Nenana\" which should return a link to https://waterdata.usgs.gov/monitoring-location/USGS-15515500/. This page contains an overview of the available data, including daily discharge data. \n",
"\n",
"The IEC standard recommends 10 years of daily discharge data for calculations of annual energy produced (AEP). The timeframe shows that at least 10 years of data is available. Clicking on the \"Daily Data\" will bring up a page that would allow the user to request data from the site. Each of the \"Available Parameters\" has a 5 digit code in front of it which will depend on the data type and reported units. The user at this point could use the website to download the data, however, the `request_usgs_data` function is used here."
"The IEC standard recommends 10 years of daily discharge data for calculations of annual energy produced (AEP). The timeframe shows that at least 10 years of data is available. Each parameter has a 5 digit USGS parameter code (e.g. 00060 for discharge in cubic feet per second), which depends on the data type and reported units. The user at this point could use the website to download the data, however, the `request_usgs_data` function is used here.\n",
"\n",
"`request_usgs_data` uses the [USGS Water Data APIs](https://api.waterdata.usgs.gov/docs/ogcapi/). An API key lets you make more requests per hour before being rate limited. Request a free key at https://api.waterdata.usgs.gov/signup and set it as the `USGS_API_KEY` environment variable before starting Python:\n",
"\n",
"```bash\n",
"export USGS_API_KEY=\"your-api-key\" # macOS/Linux\n",
"setx USGS_API_KEY \"your-api-key\" # Windows (takes effect in new terminals)\n",
"```\n",
"\n",
"or set it from Python before calling `request_usgs_data`:\n",
"\n",
"```python\n",
"import os\n",
"\n",
"os.environ[\"USGS_API_KEY\"] = \"your-api-key\"\n",
"```\n",
"\n",
"The key can also be passed directly with `options={\"api_key\": \"your-api-key\"}`."
]
},
{
Expand Down Expand Up @@ -74,6 +91,7 @@
"# Here we load 10 years of daily discharge data \n",
"data = pd.read_csv(\"data/river/usgs_discharge_TRTS_20090801_20190801_daily.csv\", index_col=0)\n",
"\n",
"# Set the USGS_API_KEY environment variable to raise the USGS API rate limit.\n",
"# The previous data was created with the following mhkit call:\n",
"# data = river.io.usgs.request_usgs_data(\n",
"# station=\"15515500\",\n",
Expand Down
Loading
Loading