docs(examples): align notebook narratives with the Water Data API

The half-migrated Hydroshare notebooks had code on waterdata.* but markdown still describing the old nwis API. Complete the narrative migration:
- remove the stray, unused "from dataretrieval import nwis" imports
- fix "...from NWIS" wording in print statements and prose -> the Water Data API
- rewrite titles, Basic-Usage function names + argument lists (waterdata args such as monitoring_location_id, parameter_code, time, statistic_id, skip_geometry instead of sites/parameterCd/statCd/start/end), and Interpreting/behavior sections (waterdata returns a flat DataFrame with a time column, not a date-indexed frame) to match the actual waterdata functions (get_daily, get_continuous, get_field_measurements, get_monitoring_locations, get_reference_table).
Markdown-only changes; code cells unchanged; notebooks remain output-free.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: thodson-usgs

demos/hydroshare/USGS_WaterData_DailyValues_Examples.ipynb

@@ -4,9 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# USGS dataretrieval Python Package `get_dv()` Examples\n",
+    "# USGS dataretrieval Python Package `get_daily()` Examples\n",
     "\n",
-    "This notebook provides examples of using the Python dataretrieval package to retrieve daily streamflow data for a United States Geological Survey (USGS) monitoring site. The dataretrieval package provides a collection of functions to get data from the USGS National Water Information System (NWIS) and other online sources of hydrology and water quality data, including the United States Environmental Protection Agency (USEPA)."
+    "This notebook provides examples of using the Python dataretrieval package to retrieve daily streamflow data for a United States Geological Survey (USGS) monitoring location. The dataretrieval package provides a collection of functions to get data from the USGS Water Data API and other online sources of hydrology and water quality data."
    ]
   },
   {
@@ -39,35 +39,30 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": [
-    "from IPython.display import display\n",
-    "\n",
-    "from dataretrieval import nwis\n",
-    "import dataretrieval.waterdata as waterdata"
-   ]
+   "source": "from IPython.display import display\n\nimport dataretrieval.waterdata as waterdata"
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### Basic Usage\n",
     "\n",
-    "The dataretrieval package has several functions that allow you to retrieve data from different web services. This examples uses the `get_dv()` function to retrieve daily streamflow data for a USGS monitoring site from NWIS. The following arguments are supported:\n",
+    "The dataretrieval package has several functions that allow you to retrieve data from different web services. This example uses the `get_daily()` function to retrieve daily streamflow data for a USGS monitoring location from the USGS Water Data API. The following arguments are supported:\n",
     "\n",
     "Arguments (Additional arguments, if supplied, will be used as query parameters)\n",
     "\n",
-    "* **sites** (string or list of strings): A list of USGS site identifiers for which to retrieve data.\n",
-    "* **parameterCd** (list of strings): A list of USGS parameter codes for which to retrieve data.\n",
-    "* **statCd** (list of strings): A list of USGS statistic codes for which to retrieve data.\n",
-    "* **start** (string): The beginning date for a period for which to retrieve data. If the waterdata parameter startDT is supplied, it will overwrite the start parameter.\n",
-    "* **end** (string): The ending date for a period for which to retrieve data. If the waterdata parameter endDT is supplied, it will overwrite the end parameter."
+    "* **monitoring_location_id** (string or iterable of strings): A unique identifier representing a single monitoring location, formed by combining the agency code with the site number (e.g. `USGS-10109000`). Accepts a single ID or a list of IDs.\n",
+    "* **parameter_code** (string or iterable of strings): One or more 5-digit USGS parameter codes identifying the constituent measured and its units of measure (e.g. `00060` for discharge).\n",
+    "* **statistic_id** (string or iterable of strings): One or more codes corresponding to the statistic an observation represents (e.g. `00001` for maximum, `00003` for mean).\n",
+    "* **time** (string): The date or interval an observation represents, following RFC 3339. May be a single date, a bounded or half-bounded interval (e.g. `2020-10-01/2021-09-30`), or an ISO 8601 duration (e.g. `P7D` for the past seven days).\n",
+    "* **skip_geometry** (boolean): If `True`, response geometries are omitted and the returned data frame contains no spatial information."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Example 1: Get daily value data for a specific parameter at a single USGS NWIS monitoring site between a begin and end date."
+    "Example 1: Get daily value data for a specific parameter at a single USGS monitoring location between a begin and end date."
    ]
   },
   {
@@ -83,7 +78,7 @@
    "source": [
     "### Interpreting the Result\n",
     "\n",
-    "The result of calling the `get_dv()` function is an object that contains a Pandas data frame object and an associated metadata object. The Pandas data frame contains the daily values for the observed variable and time period requested. The data frame is indexed by the dates associated with the data values.\n",
+    "The `get_daily()` function returns a tuple containing a pandas data frame and an associated metadata object. The data frame contains the daily values for the observed variable and time period requested. It is a flat table with a default integer index; the dates associated with each observation are held in a `time` column rather than in the index.\n",
     "\n",
     "Once you've got the data frame, there's several useful things you can do to explore the data."
    ]
@@ -148,35 +143,31 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The other part of the result returned from the `get_dv()` function is a metadata object that contains information about the query that was executed to return the data. For example, you can access the URL that was assembled to retrieve the requested data from the USGS web service. The USGS web service responses contain a descriptive header that defines and can be helpful in interpreting the contents of the response."
+    "The other part of the result returned from the `get_daily()` function is a metadata object that contains information about the query that was executed to return the data. For example, you can access the URL that was assembled to retrieve the requested data from the USGS Water Data API."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": [
-    "print(\n",
-    "    \"The query URL used to retrieve the data from NWIS was: \" + dailyStreamflow[1].url\n",
-    ")"
-   ]
+   "source": "print(\n    \"The query URL used to retrieve the data from the Water Data API was: \" + dailyStreamflow[1].url\n)"
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### Additional Examples\n",
     "\n",
-    "Example 2: Get daily mean and max discharge and temperature values for a site between a begin and end date.\n",
+    "Example 2: Get daily mean and max discharge and temperature values for a location between a begin and end date.\n",
     "\n",
     "Parameter Code: 00010 = temperature, 00060 = discharge\n",
     "See https://help.waterdata.usgs.gov/codes-and-parameters/parameters\n",
     "\n",
     "Statistic Code: 00001 = Maximum, 00003 = Mean\n",
     "See https://help.waterdata.usgs.gov/stat_code\n",
     "\n",
-    "NOTE: There's not full overlap in the availability of data for temperature and discharge for both statistics at this site. When data for one statistic is not available, a \"NaN\" value is returned in the data frame."
+    "NOTE: There's not full overlap in the availability of data for temperature and discharge for both statistics at this location."
    ]
   },
   {
@@ -190,7 +181,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Example 3: Get daily mean and max discharge and temperature values for multiple sites between a begin and end date"
+    "Example 3: Get daily mean and max discharge and temperature values for multiple monitoring locations between a begin and end date."
    ]
   },
   {
@@ -204,7 +195,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The following example is the same as the previous example but with multi index turned off (multi_index=False)"
+    "Like all of the waterdata getters, `get_daily()` returns a flat data frame with a default integer index regardless of how many monitoring locations are requested. Each row carries its own `monitoring_location_id`, `parameter_code`, `statistic_id`, and `time`, so multi-location results can be filtered or pivoted as needed."
    ]
   },
   {
@@ -218,7 +209,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Example 4: Test for a site that is not active - returns an empty DataFrame."
+    "Example 4: Query a location that has no matching data for the requested period - returns an empty DataFrame."
    ]
   },
   {

demos/hydroshare/USGS_WaterData_GroundwaterLevels_Examples.ipynb

@@ -4,9 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# USGS dataretrieval Python Package `get_gwlevels()` Examples\n",
+    "# USGS dataretrieval Python Package `get_field_measurements()` Examples\n",
     "\n",
-    "This notebook provides examples of using the Python dataretrieval package to retrieve groundwater level data for a United States  Geological Survey (USGS) monitoring site. The dataretrieval package provides a collection of functions to get data from the USGS National Water Information System (NWIS) and other online sources of hydrology and water quality data, including the United States Environmental Protection Agency (USEPA)."
+    "This notebook provides examples of using the Python dataretrieval package to retrieve groundwater level field measurements for a United States Geological Survey (USGS) monitoring location. The dataretrieval package provides a collection of functions to get data from the USGS Water Data API and other online sources of hydrology and water quality data."
    ]
   },
   {
@@ -39,33 +39,27 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": [
-    "from IPython.display import display\n",
-    "\n",
-    "from dataretrieval import nwis\n",
-    "import dataretrieval.waterdata as waterdata"
-   ]
+   "source": "from IPython.display import display\n\nimport dataretrieval.waterdata as waterdata"
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### Basic Usage\n",
     "\n",
-    "The dataretrieval package has several functions that allow you to retrieve data from different web services. This examples uses the `get_gwlevels()` function to retrieve groundwater level data from USGS NWIS. The following arguments are supported:\n",
+    "The dataretrieval package has several functions that allow you to retrieve data from different services of the USGS Water Data API. This example uses the `get_field_measurements()` function to retrieve groundwater level field measurements. Field measurements are physically measured values collected during a visit to a monitoring location and are commonly used to record groundwater levels. The following arguments are commonly used:\n",
     "\n",
-    "Arguments (Additional parameters, if supplied, will be used as query parameters)\n",
-    "\n",
-    "* **sites** (string or list of strings): A list of USGS site identifiers for which to retrieve data.\n",
-    "* **start** (string): The beginning date for a period for which to retrieve data. If the waterdata parameter begin_date is supplied, it will overwrite the start parameter (defaults to '1851-01-01')\n",
-    "* **end** (string): The ending date for a period for which to retrieve data. If the waterdata parameter end_date is supplied, it will overwrite the end parameter."
+    "* **monitoring_location_id** (string or list of strings): A unique identifier representing one or more monitoring locations. IDs combine the responsible agency code with the location number, separated by a hyphen (e.g. `USGS-434400121275801`).\n",
+    "* **parameter_code** (string or list of strings): One or more 5-digit codes identifying the constituent measured and its units of measure.\n",
+    "* **time** (string): The date an observation represents. Accepts a single RFC 3339 date-time, a bounded or half-bounded interval (e.g. `\"1980-01-01/2000-12-31\"`, `\"1980-01-01/..\"`), or an ISO 8601 duration (e.g. `\"P20Y\"`). Only observations whose time intersects this value are returned.\n",
+    "* **skip_geometry** (boolean): If `True`, response geometries are omitted and the returned data frame contains no spatial information."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Example 1: Get groundwater level data for a single monitoring site."
+    "Example 1: Get groundwater level field measurements for a single monitoring location."
    ]
   },
   {
@@ -81,7 +75,7 @@
    "source": [
     "### Interpreting the Result\n",
     "\n",
-    "The result of calling the `get_gwlevels()` function is an object that contains a Pandas data frame and an associated metadata object. The Pandas data frame contains the data requested. The data frame is indexed by the dates associated with the data values.\n",
+    "The `get_field_measurements()` function returns a tuple of two objects: a pandas data frame containing the requested data and an associated metadata object. The data frame is flat, using a default integer index, and the observation dates are held in its `time` column.\n",
     "\n",
     "Once you've got the data frame, there's several useful things you can do to explore the data."
    ]
@@ -122,7 +116,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Get summary statistics for the daily streamflow values."
+    "Get summary statistics for the measured groundwater level values."
    ]
   },
   {
@@ -152,7 +146,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The other part of the result returned from the `get_gwlevels()` function is a metadata object that contains information about the query that was executed to return the data. For example, you can access the URL that was assembled to retrieve the requested data from the USGS web service. The USGS web service responses contain a descriptive header that defines and can be helpful in interpreting the contents of the response."
+    "The other part of the result returned from the `get_field_measurements()` function is a metadata object that contains information about the query that was executed to return the data. For example, you can access the URL that was assembled to retrieve the requested data from the USGS Water Data API."
    ]
   },
   {
@@ -186,7 +180,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The following example is the same as the previous example but with multi index turned off (multi_index=False)"
+    "The following example requests the same data as the previous example, again passing the site identifiers as a list of strings."
    ]
   },
   {
@@ -216,18 +210,15 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If you want to see the USGS RDB (delimited text) version of the data just retrieved, you can get the URL for the request that was sent to the USGS web service."
+    "If you want to inspect the request that was sent, you can get the URL for the query that was issued to the USGS Water Data API."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": [
-    "# Print the URL used to retrieve the data\n",
-    "print(\"You can examine the data retrieved from NWIS at: \" + data3[1].url)"
-   ]
+   "source": "# Print the URL used to retrieve the data\nprint(\"You can examine the data retrieved from the Water Data API at: \" + data3[1].url)"
   },
   {
    "cell_type": "markdown",