correct example documentation and add info about logging

Author: ehinman

README.md

@@ -6,7 +6,7 @@
 
 ## Latest Announcements
 
-:mega: **10/01/2025:** `dataretrieval` now features the new `waterdata` module,
+:mega: **11/24/2025:** `dataretrieval` now features the new `waterdata` module,
 which provides access to USGS's modernized [Water Data
 APIs](https://api.waterdata.usgs.gov/). The Water Data API endpoints include
 daily values, instantaneous values, field measurements, time series metadata,
@@ -65,6 +65,23 @@ locations, metadata = waterdata.get_monitoring_locations(
 
 print(f"Found {len(locations)} stream monitoring locations in Maryland")
 ```
+This new module implements
+[logging](https://docs.python.org/3/howto/logging.html#logging-basic-tutorial)
+in which users can view the URL requests sent to the USGS Water Data APIs
+and the number of requests they have remaining each hour. These messages can
+be helpful for troubleshooting and support. To enable logging in your python
+console or notebook:
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+``` 
+To log messages to a file, you can specify a filename in the
+`basicConfig` call:
+
+```python
+logging.basicConfig(filename='waterdata.log', level=logging.INFO)
+```
 
 ### NWIS Legacy Services (Deprecated but still functional)
 

dataretrieval/waterdata/api.py

@@ -188,8 +188,7 @@ def get_daily(
         ...     time="2021-01-01T00:00:00Z/2022-01-01T00:00:00Z",
         ... )
 
-        >>> # Get monitoring location info for specific sites
-        >>> # and only specific properties
+        >>> # Get approved daily flow data from multiple sites
         >>> df, md = dataretrieval.waterdata.get_daily(
         ...     monitoring_location_id = ["USGS-05114000", "USGS-09423350"],
         ...     approval_status = "Approved",
@@ -678,19 +677,18 @@ def get_time_series_metadata(
     --------
     .. code::
 
-        >>> # Get daily flow data from a single site
+        >>> # Get timeseries metadata information from a single site
         >>> # over a yearlong period
         >>> df, md = dataretrieval.waterdata.get_time_series_metadata(
-        ...     monitoring_location_id="USGS-02238500",
-        ...     parameter_code="00060",
-        ...     time="2021-01-01T00:00:00Z/2022-01-01T00:00:00Z",
+        ...     monitoring_location_id="USGS-02238500"
         ... )
 
-        >>> # Get monitoring location info for specific sites
-        >>> # and only specific properties
+        >>> # Get timeseries metadata information from multiple sites
+        >>> # that begin after January 1, 1990.
         >>> df, md = dataretrieval.waterdata.get_time_series_metadata(
         ...     monitoring_location_id = ["USGS-05114000", "USGS-09423350"],
-        ...     time = "2024-01-01/.."
+        ...     begin = "1990-01-01/.."
+        ... )
     """
     service = "time-series-metadata"
     output_id = "time_series_id"
@@ -856,14 +854,12 @@ def get_latest_continuous(
     --------
     .. code::
 
-        >>> # Get daily flow data from a single site
-        >>> # over a yearlong period
+        >>> # Get latest flow data from a single site
         >>> df, md = dataretrieval.waterdata.get_latest_continuous(
         ...     monitoring_location_id="USGS-02238500", parameter_code="00060"
         ... )
 
-        >>> # Get monitoring location info for specific sites
-        >>> # and only specific properties
+        >>> # Get latest continuous measurements for multiple sites
         >>> df, md = dataretrieval.waterdata.get_latest_continuous(
         ...     monitoring_location_id=["USGS-05114000", "USGS-09423350"]
         ... )
@@ -1034,14 +1030,12 @@ def get_latest_daily(
     --------
     .. code::
 
-        >>> # Get daily flow data from a single site
-        >>> # over a yearlong period
+        >>> # Get most recent daily flow data from a single site
         >>> df, md = dataretrieval.waterdata.get_latest_daily(
         ...     monitoring_location_id="USGS-02238500", parameter_code="00060"
         ... )
 
-        >>> # Get monitoring location info for specific sites
-        >>> # and only specific properties
+        >>> # Get most recent daily measurements for two sites
         >>> df, md = dataretrieval.waterdata.get_latest_daily(
         ...     monitoring_location_id=["USGS-05114000", "USGS-09423350"]
         ... )
@@ -1201,16 +1195,16 @@ def get_field_measurements(
     --------
     .. code::
 
-        >>> # Get daily flow data from a single site
-        >>> # over a yearlong period
+        >>> # Get field measurements from a single groundwater site
+        >>> # and parameter code, and do not return geometry
         >>> df, md = dataretrieval.waterdata.get_field_measurements(
         ...     monitoring_location_id="USGS-375907091432201",
         ...     parameter_code="72019",
         ...     skip_geometry=True,
         ... )
 
-        >>> # Get monitoring location info for specific sites
-        >>> # and only specific properties
+        >>> # Get field measurements from multiple sites and
+        >>> # parameter codes from the last 20 years
         >>> df, md = dataretrieval.waterdata.get_field_measurements(
         ...     monitoring_location_id = ["USGS-451605097071701",
                                           "USGS-263819081585801"],