Python Equivalents to R Vignette Examples

[1]:
from dataretrieval import waterdata, wqp

The dataretrieval Python package was created as an equivalent to the R dataRetrieval package.

The following shows Python equivalents for the methods outlined in the R dataRetrieval vignette, with the equivalent R code in comments.

[2]:
"""
{r getSite, echo=TRUE, eval=FALSE}
siteNumbers <- c("01491000","01645000")
siteINFO <- readNWISsite(siteNumbers)
"""
siteNumbers = ["USGS-01491000", "USGS-01645000"]
siteINFO, md = waterdata.get_monitoring_locations(
    monitoring_location_id=siteNumbers, skip_geometry=True
)
Retrieving: monitoring-locations · 1 page · 2 rows
No API key detected — register for higher rate limits at https://api.waterdata.usgs.gov/signup/
[3]:
"""
# Continuing from the previous example:
# This pulls out just the daily, mean data:
dailyDataAvailable <- whatNWISdata(siteNumbers,
                    service="dv", statCd="00003")
"""
dailyDataAvailable, md = waterdata.get_time_series_metadata(
    monitoring_location_id=siteNumbers, statistic_id="00003", skip_geometry=True
)
Retrieving: time-series-metadata · 1 page · 11 rows
[4]:
"""
# Choptank River near Greensboro, MD:
siteNumber <- "01491000"
parameterCd <- "00060"  # Discharge
startDate <- "2009-10-01"
endDate <- "2012-09-30"

discharge <- readNWISdv(siteNumber, parameterCd, startDate, endDate)
"""
# Choptank River near Greensboro, MD:
siteNumber = "USGS-01491000"
parameterCd = "00060"  # Discharge

discharge, md = waterdata.get_daily(
    monitoring_location_id=siteNumber,
    parameter_code=parameterCd,
    time="2009-10-01/2012-09-30",
)
Retrieving: daily · 1 page · 1,096 rows
[5]:
"""
siteNumber <- "01491000"
parameterCd <- c("00010","00060")  # Temperature and discharge
statCd <- c("00001","00003")  # Maximum and mean
startDate <- "2012-01-01"
endDate <- "2012-05-01"

temperatureAndFlow <- readNWISdv(siteNumber, parameterCd, startDate, endDate, statCd=statCd)
"""
siteNumber = "USGS-01491000"
parameterCd = ["00010", "00060"]  # Temperature and discharge
statisticId = ["00001", "00003"]  # Maximum and mean

temperatureAndFlow, md = waterdata.get_daily(
    monitoring_location_id=siteNumber,
    parameter_code=parameterCd,
    statistic_id=statisticId,
    time="2012-01-01/2012-05-01",
)
Retrieving: daily · 1 page · 364 rows
[6]:
"""
parameterCd <- "00060"  # Discharge
startDate <- "2012-05-12"
endDate <- "2012-05-13"
dischargeUnit <- readNWISuv(siteNumber, parameterCd, startDate, endDate)
"""
siteNumber = "USGS-01491000"
parameterCd = "00060"  # Discharge

dischargeUnit, md = waterdata.get_continuous(
    monitoring_location_id=siteNumber,
    parameter_code=parameterCd,
    time="2012-05-12/2012-05-13",
)
Retrieving: continuous · 1 page · 97 rows
[7]:
"""
# Dissolved Nitrate parameter codes:
parameterCd <- c("00618","71851")
startDate <- "1985-10-01"
endDate <- "2012-09-30"
dfLong <- read_USGS_samples(monitoringLocationIdentifier=sprintf("USGS-%s", siteNumber),
      usgsPCode=parameterCd, activityStartDateLower=startDate, activityStartDateUpper=endDate)
"""
siteNumber = "USGS-01491000"
parameterCd = ["00618", "71851"]

dfLong, md = waterdata.get_samples(
    monitoringLocationIdentifier=siteNumber,
    usgsPCode=parameterCd,
    activityStartDateLower="1985-10-01",
    activityStartDateUpper="2012-09-30",
)
/tmp/ipykernel_7012/2092726829.py:12: DeprecationWarning: The 'activityStartDateLower' argument is deprecated and will be removed from `dataretrieval` in a future release; use 'activity_start_date_lower' instead.
  dfLong, md = waterdata.get_samples(
/tmp/ipykernel_7012/2092726829.py:12: DeprecationWarning: The 'activityStartDateUpper' argument is deprecated and will be removed from `dataretrieval` in a future release; use 'activity_start_date_upper' instead.
  dfLong, md = waterdata.get_samples(
/tmp/ipykernel_7012/2092726829.py:12: DeprecationWarning: The 'usgsPCode' argument is deprecated and will be removed from `dataretrieval` in a future release; use 'usgs_pcode' instead.
  dfLong, md = waterdata.get_samples(
/tmp/ipykernel_7012/2092726829.py:12: DeprecationWarning: The 'monitoringLocationIdentifier' argument is deprecated and will be removed from `dataretrieval` in a future release; use 'monitoring_location_id' instead.
  dfLong, md = waterdata.get_samples(
[8]:
"""
siteNumber <- '01594440'
peakData <- readNWISpeak(siteNumber)
"""
peakData, md = waterdata.get_peaks(
    monitoring_location_id="USGS-01594440", parameter_code="00060"
)
---------------------------------------------------------------------------
RateLimited                               Traceback (most recent call last)
File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/transport/fanout.py:615, in FanOut._run.<locals>.track(index, item)
    614 """One chunk (with retry) + result-store + progress update."""
--> 615 result = await _retry(
    616     lambda: self.fetch(item), self.retry_policy, gate=semaphore
    617 )
    618 self._chunks[index] = result

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/transport/retry.py:291, in retry_async(afn, policy, gate)
    290 try:
--> 291     return await attempt_once()
    292 except Exception as exc:

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/transport/retry.py:287, in retry_async.<locals>.attempt_once()
    286 credit_wait(time.monotonic() - started)
--> 287 return await afn()

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/ogc/engine.py:420, in _fetch_once(args, build_request, geopd, include_geometry, row_cap)
    419 req = build_request(**args)
--> 420 return await _walk_pages(
    421     geopd=geopd,
    422     req=req,
    423     include_geometry=include_geometry,
    424     row_cap=row_cap,
    425 )

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/ogc/engine.py:203, in _walk_pages(geopd, req, client, include_geometry, row_cap)
    201     return await sess.request(method, cursor, headers=headers, content=content)
--> 203 return await paginate(
    204     req,
    205     parse_response=functools.partial(
    206         _ogc_parse_response,
    207         geopd=geopd,
    208         include_geometry=include_geometry,
    209     ),
    210     follow_up=follow_up,
    211     client=client,
    212     raise_for_status=_raise_for_non_200,
    213     row_cap=row_cap,
    214 )

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/transport/pagination.py:112, in paginate(initial_req, parse_response, follow_up, raise_for_status, client, row_cap)
    111 response = await session.send(initial_req)
--> 112 raise_for_status(response)
    113 initial_response = response

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/ogc/errors.py:139, in _raise_for_non_200(resp)
    138     return
--> 139 raise error_for_status(
    140     status,
    141     _error_body(resp) + _url_suffix(resp),
    142     retry_after=_parse_retry_after(resp.headers.get("Retry-After")),
    143 )

RateLimited: 429: Too many requests made. Please obtain an API token or try again later. (URL: https://api.waterdata.usgs.gov/ogcapi/v1/collections/peaks/items?monitoring_location_id=USGS-01594440&parameter_code=00060&limit=50000)

The above exception was the direct cause of the following exception:

QuotaExhausted                            Traceback (most recent call last)
Cell In[8], line 5
      1 """
      2 siteNumber <- '01594440'
      3 peakData <- readNWISpeak(siteNumber)
      4 """
----> 5 peakData, md = waterdata.get_peaks(
      6     monitoring_location_id="USGS-01594440", parameter_code="00060"
      7 )

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/waterdata/measurements.py:425, in get_peaks(monitoring_location_id, parameter_code, time_series_id, unit_of_measure, time, last_modified, water_year, year, month, day, peak_since, properties, skip_geometry, bbox, limit, filter, filter_lang, convert_type, max_rows, qualifier, time_of_day, value, **queryables)
    421 collection = "peaks"
    423 args = _get_args(locals(), exclude={"max_rows"})
--> 425 return get_ogc_data(args, collection, max_rows=max_rows)

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/waterdata/utils.py:268, in get_ogc_data(args, collection, output_id, max_rows, cql_body, spatial, api_version)
    266 if output_id is None:
    267     output_id = _OUTPUT_ID_BY_COLLECTION[collection]
--> 268 return _facade_get_ogc_data(
    269     args,
    270     collection,
    271     output_id,
    272     max_rows=max_rows,
    273     # The endpoint is resolved from the active ContextVar at request time;
    274     # the documented ``OGC_API_URL`` constant remains the default-value
    275     # compatibility path rather than a production request destination.
    276     base_url=ogc_api_url(api_version=api_version),
    277     spatial=spatial,
    278     extra_id_cols=_EXTRA_ID_COLS,
    279     dialect=WATERDATA_DIALECT,
    280     cql_body=cql_body,
    281     # Which settings table these calls read. Declared here, in the one
    282     # wrapper every Water Data getter goes through, rather than derived
    283     # from ``base_url``: NGWMN is served from the same host, so a URL
    284     # does not distinguish the two adapters (ADR 0010).
    285     adapter="waterdata",
    286 )

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/ogc/engine.py:394, in get_ogc_data(args, collection, output_id, base_url, spatial, max_rows, extra_id_cols, dialect, cql_body, adapter)
    389 run = chunking.multi_value_chunked(build_request=build_request, adapter=adapter)(
    390     fetch
    391 )
    392 # No progress block here: the executor that emits the events owns the line
    393 # (see :meth:`~dataretrieval.transport.fanout.FanOut.resume`).
--> 394 return run(args, finalize=finalize)

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/ogc/chunking.py:261, in multi_value_chunked.<locals>.decorator.<locals>.wrapper(args, finalize)
    247 retry_policy = RetryPolicy.from_configuration(adapter=adapter)
    248 # The concurrency cap is resolved inside ``resume()`` through the
    249 # configuration chain; ``1`` is a sequential gather,
    250 # ``total <= 1`` a one-element gather — no special branch.
    251 return ChunkedCall(
    252     plan,
    253     fetch,
    254     retry_policy,
    255     finalize,
    256     canonical_url=plan.canonical_url,
    257     # The collection name, for the progress line the executor
    258     # opens. ``get_ogc_data`` puts it in ``args``.
    259     service=args.get("collection"),
    260     adapter=adapter,
--> 261 ).resume()

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/transport/fanout.py:494, in FanOut.resume(self)
    486 concurrency = _configuration.concurrency(
    487     self.default_concurrent, adapter=self.adapter
    488 )
    489 with start_blocking_portal() as portal:
    490     # ``portal.call`` returns ``Any`` because ``functools.partial``
    491     # erases ``_run``'s return type; restore the declared tuple.
    492     return cast(
    493         "tuple[pd.DataFrame, Any]",
--> 494         portal.call(functools.partial(self._run, concurrency)),
    495     )

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/anyio/from_thread.py:347, in BlockingPortal.call(self, func, *args)
    332 def call(
    333     self,
    334     func: Callable[[Unpack[PosArgsT]], Awaitable[T_Retval] | T_Retval],
    335     *args: Unpack[PosArgsT],
    336 ) -> T_Retval:
    337     """
    338     Call the given function in the event loop thread.
    339
   (...)    345
    346     """
--> 347     return cast(T_Retval, self.start_task_soon(func, *args).result())

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/concurrent/futures/_base.py:460, in Future.result(self, timeout)
    458     raise CancelledError()
    459 elif self._state == FINISHED:
--> 460     return self.__get_result()
    461 else:
    462     raise TimeoutError()

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/concurrent/futures/_base.py:402, in Future.__get_result(self)
    400 if self._exception is not None:
    401     try:
--> 402         raise self._exception
    403     finally:
    404         # Break a reference cycle with the exception in self._exception
    405         self = None

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/anyio/from_thread.py:272, in BlockingPortal._call_func(self, func, args, kwargs, future)
    270     with CancelScope() as scope:
    271         future.add_done_callback(callback)
--> 272         retval = await retval_or_awaitable
    273 else:
    274     retval = retval_or_awaitable

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/transport/fanout.py:633, in FanOut._run(self, max_concurrent)
    625         # Dispatch every pending chunk concurrently; the
    626         # semaphore (held by ``_retry`` per attempt) is the only throttle.
    627         # ``return_exceptions`` keeps completed pairs after a sibling
    628         # fails, so partial state stays recoverable via :meth:`resume`.
    629         results = await asyncio.gather(
    630             *(track(index, item) for index, item in self._pending()),
    631             return_exceptions=True,
    632         )
--> 633         self._handle_gather_failures(results)
    635 return self.finalize(*self._combine_raw())

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/transport/fanout.py:540, in FanOut._handle_gather_failures(self, results)
    537 if interrupted is None:
    538     # Unreachable: classified as transient above.
    539     raise self._normalize_failure(first_transient)
--> 540 raise interrupted from first_transient

QuotaExhausted: HTTP 429 after 0/1 chunks; catch QuotaExhausted (or FanOutInterrupted) to access .partial_frame or .call.resume() once the rate-limit window has reset. Cause: RateLimited: 429: Too many requests made. Please obtain an API token or try again later. (URL: https://api.waterdata.usgs.gov/ogcapi/v1/collections/peaks/items?monitoring_location_id=USGS-01594440&parameter_code=00060&limit=50000)
[9]:
"""
ratingData <- readNWISrating(siteNumber, "base")
attr(ratingData, "RATING")
"""
# get_ratings returns a dict keyed by "<id>.<file_type>.rdb"
ratings_data = waterdata.get_ratings(
    monitoring_location_id="USGS-01594440", file_type="base"
)
list(ratings_data.keys())
Retrieving: ratings · 1 page · 1 rows
---------------------------------------------------------------------------
RateLimited                               Traceback (most recent call last)
File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/transport/fanout.py:615, in FanOut._run.<locals>.track(index, item)
    614 """One chunk (with retry) + result-store + progress update."""
--> 615 result = await _retry(
    616     lambda: self.fetch(item), self.retry_policy, gate=semaphore
    617 )
    618 self._chunks[index] = result

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/transport/retry.py:291, in retry_async(afn, policy, gate)
    290 try:
--> 291     return await attempt_once()
    292 except Exception as exc:

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/transport/retry.py:287, in retry_async.<locals>.attempt_once()
    286 credit_wait(time.monotonic() - started)
--> 287 return await afn()

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/waterdata/ratings.py:434, in _download_all.<locals>.fetch(feature)
    433 try:
--> 434     df, response = await _fetch_rating(feature, file_path)
    435 except (DataRetrievalError, LookupError, ValueError) as e:

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/waterdata/ratings.py:385, in _fetch_rating(feature, file_path)
    384 response = await session.get(href, headers=headers)
--> 385 _raise_for_non_200(response)
    387 if file_path is not None:

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/ogc/errors.py:139, in _raise_for_non_200(resp)
    138     return
--> 139 raise error_for_status(
    140     status,
    141     _error_body(resp) + _url_suffix(resp),
    142     retry_after=_parse_retry_after(resp.headers.get("Retry-After")),
    143 )

RateLimited: 429: Too many requests made. Please obtain an API token or try again later. (URL: https://api.waterdata.usgs.gov/stac-files/ratings/USGS.01594440.base.rdb)

The above exception was the direct cause of the following exception:

QuotaExhausted                            Traceback (most recent call last)
Cell In[9], line 6
      2 ratingData <- readNWISrating(siteNumber, "base")
      3 attr(ratingData, "RATING")
      4 """
      5 # get_ratings returns a dict keyed by "<id>.<file_type>.rdb"
----> 6 ratings_data = waterdata.get_ratings(
      7     monitoring_location_id="USGS-01594440", file_type="base"
      8 )
      9 list(ratings_data.keys())

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/waterdata/ratings.py:208, in get_ratings(monitoring_location_id, file_type, file_path, time, bbox, limit, download_and_parse, ssl_check)
    205 if file_path is not None:
    206     os.makedirs(file_path, exist_ok=True)
--> 208 return _download_all(matching, file_path, ssl_check)

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/waterdata/ratings.py:462, in _download_all(features, file_path, ssl_check)
    447     out[fid] = df
    448     return df, _inert_response(
    449         response.status_code, str(response.url), response.headers
    450     )
    452 FanOut(
    453     features,
    454     fetch,
    455     RetryPolicy.from_configuration(adapter="waterdata"),
    456     client_options={"verify": ssl_check},
    457     # No single URL expresses "all of these assets" -- the aggregate
    458     # reports the first, matching what a single-feature call would show.
    459     canonical_url=_asset_href(features[0]),
    460     service="ratings",
    461     adapter="waterdata",
--> 462 ).resume()
    463 return out

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/transport/fanout.py:494, in FanOut.resume(self)
    486 concurrency = _configuration.concurrency(
    487     self.default_concurrent, adapter=self.adapter
    488 )
    489 with start_blocking_portal() as portal:
    490     # ``portal.call`` returns ``Any`` because ``functools.partial``
    491     # erases ``_run``'s return type; restore the declared tuple.
    492     return cast(
    493         "tuple[pd.DataFrame, Any]",
--> 494         portal.call(functools.partial(self._run, concurrency)),
    495     )

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/anyio/from_thread.py:347, in BlockingPortal.call(self, func, *args)
    332 def call(
    333     self,
    334     func: Callable[[Unpack[PosArgsT]], Awaitable[T_Retval] | T_Retval],
    335     *args: Unpack[PosArgsT],
    336 ) -> T_Retval:
    337     """
    338     Call the given function in the event loop thread.
    339
   (...)    345
    346     """
--> 347     return cast(T_Retval, self.start_task_soon(func, *args).result())

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/concurrent/futures/_base.py:460, in Future.result(self, timeout)
    458     raise CancelledError()
    459 elif self._state == FINISHED:
--> 460     return self.__get_result()
    461 else:
    462     raise TimeoutError()

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/concurrent/futures/_base.py:402, in Future.__get_result(self)
    400 if self._exception is not None:
    401     try:
--> 402         raise self._exception
    403     finally:
    404         # Break a reference cycle with the exception in self._exception
    405         self = None

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/anyio/from_thread.py:272, in BlockingPortal._call_func(self, func, args, kwargs, future)
    270     with CancelScope() as scope:
    271         future.add_done_callback(callback)
--> 272         retval = await retval_or_awaitable
    273 else:
    274     retval = retval_or_awaitable

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/transport/fanout.py:633, in FanOut._run(self, max_concurrent)
    625         # Dispatch every pending chunk concurrently; the
    626         # semaphore (held by ``_retry`` per attempt) is the only throttle.
    627         # ``return_exceptions`` keeps completed pairs after a sibling
    628         # fails, so partial state stays recoverable via :meth:`resume`.
    629         results = await asyncio.gather(
    630             *(track(index, item) for index, item in self._pending()),
    631             return_exceptions=True,
    632         )
--> 633         self._handle_gather_failures(results)
    635 return self.finalize(*self._combine_raw())

File /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/transport/fanout.py:540, in FanOut._handle_gather_failures(self, results)
    537 if interrupted is None:
    538     # Unreachable: classified as transient above.
    539     raise self._normalize_failure(first_transient)
--> 540 raise interrupted from first_transient

QuotaExhausted: HTTP 429 after 0/1 chunks; catch QuotaExhausted (or FanOutInterrupted) to access .partial_frame or .call.resume() once the rate-limit window has reset. Cause: RateLimited: 429: Too many requests made. Please obtain an API token or try again later. (URL: https://api.waterdata.usgs.gov/stac-files/ratings/USGS.01594440.base.rdb)
[10]:
"""
discharge_stats <- readNWISstat(siteNumbers=c("02319394"),
                   parameterCd=c("00060"),
                   statReportType="annual")
"""
discharge_stats, md = waterdata.get_stats_date_range(
    monitoring_location_id="USGS-02319394",
    parameter_code="00060",
    computation_type="arithmetic_mean",
)
Retrieving: observationIntervals · 1 page · 344 rows
[11]:
# R: readNWISdata(service="dv", stateCd="WI", parameterCd="00060",
#                 drainAreaMin="50", statCd="00003")
#
# The Water Data API serves daily values per monitoring location. To assemble a
# state-wide set, first find the locations (optionally filtering by drainage
# area) with waterdata.get_monitoring_locations(state_name="Wisconsin", ...),
# then pass their ids to waterdata.get_daily(parameter_code="00060",
# statistic_id="00003").
[12]:
# '''
# sitesNJ <- whatWQPsites(statecode="US:34",
#                        characteristicName="Chloride")
# '''
# sitesNJ, md = wqp.what_sites(statecode="US:34", characteristicName="Chloride")
[13]:
# '''
# dataPH <- readWQPdata(statecode="US:55",
#                  characteristicName="pH")
# '''
# dataPH, md = wqp.what_sites(statecode="US:55", characteristicName="pH")
[14]:
# '''
# type <- "Stream"
# sites <- whatWQPdata(countycode="US:55:025",siteType=type)
# '''
# streamType = "Stream"
# sites, md = wqp.get_results(countycode="US:55:025", siteType=streamType)
[15]:
"""site <- whatWQPsamples(siteid="USGS-01594440")"""

site, md = wqp.what_sites(siteid="USGS-01594440")
/opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/wqp.py:661: DataCurrencyWarning: This function call will return the legacy WQX format, which means USGS data have not been updated since March 2024. Please review the dataretrieval-python documentation for more information on updated WQX3.0 profiles. Setting `legacy=False` will remove this warning.
  _warn_legacy_use()
[16]:
"""
type <- "Stream"
sites <- whatWQPmetrics(countycode="US:55:025",siteType=type)
"""
streamType = "Stream"
sites, md = wqp.what_sites(countycode="US:55:025", siteType=streamType)
/opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages/dataretrieval/wqp.py:661: DataCurrencyWarning: This function call will return the legacy WQX format, which means USGS data have not been updated since March 2024. Please review the dataretrieval-python documentation for more information on updated WQX3.0 profiles. Setting `legacy=False` will remove this warning.
  _warn_legacy_use()

Embedded Metadata

Most waterdata and wqp service methods return a tuple of the requested data (a pandas DataFrame) and a metadata object.

md is an object with the following attributes:

Metadata
    url         # the URL used to query the service
    query_time  # how long the query took
    header      # the response headers

Note: USGS water use data is retrieved through a separate service, nwdc.get_wateruse(), which draws on the USGS National Water Availability Assessment Data Companion (NWDC). See the water-use example notebook for details.