From 0c1d03ec7b40d85bdd1ea254dedc6fbc27223f72 Mon Sep 17 00:00:00 2001
From: thodson-usgs <thodson@usgs.gov>
Date: Sat, 30 May 2026 14:24:50 -0400
Subject: [PATCH] docs(waterdata): point get_samples to get_codes, not
 nonexistent *_lookup()
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The get_samples docstring told users 8 times to "Check the
`activityMediaName_lookup()` / `characteristicGroup_lookup()` / ... function in
this module" — but no such functions exist, so following the docs raises
AttributeError. The actual code-table mechanism is get_codes(code_service).

Repointed each parameter to the right service (all verified against the live
API): activityMediaName -> samplemedia, characteristicGroup ->
characteristicgroup, characteristic -> characteristics, usgsPCode ->
characteristics (the parameterCode column), stateFips -> states, countyFips ->
counties, siteTypeCode/siteTypeName -> sitetype.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 dataretrieval/waterdata/api.py | 29 ++++++++++++-----------------
 1 file changed, 12 insertions(+), 17 deletions(-)

diff --git a/dataretrieval/waterdata/api.py b/dataretrieval/waterdata/api.py
index 1e6d0aa0..f78958e9 100644
--- a/dataretrieval/waterdata/api.py
+++ b/dataretrieval/waterdata/api.py
@@ -2218,8 +2218,7 @@ def get_samples(
         organizations - "organization", "count"
     activityMediaName : string or iterable of strings, optional
         Name or code indicating environmental medium in which sample was taken.
-        Check the `activityMediaName_lookup()` function in this module for all
-        possible inputs.
+        Call ``get_codes("samplemedia")`` for the valid inputs.
         Example: "Water".
     activityStartDateLower : string, optional
         The start date if using a date range. Takes the format YYYY-MM-DD.
@@ -2236,13 +2235,12 @@ def get_samples(
         Example: "Sample-Routine, regular".
     characteristicGroup : string or iterable of strings, optional
         Characteristic group is a broad category of characteristics
-        describing one or more results. Check the `characteristicGroup_lookup()`
-        function in this module for all possible inputs.
+        describing one or more results. Call ``get_codes("characteristicgroup")``
+        for the valid inputs.
         Example: "Organics, PFAS"
     characteristic : string or iterable of strings, optional
         Characteristic is a specific category describing one or more results.
-        Check the `characteristic_lookup()` function in this module for all
-        possible inputs.
+        Call ``get_codes("characteristics")`` for the valid inputs.
         Example: "Suspended Sediment Discharge"
     characteristicUserSupplied : string or iterable of strings, optional
         A user supplied characteristic name describing one or more results.
@@ -2263,27 +2261,24 @@ def get_samples(
     countryFips : string or iterable of strings, optional
         Example: "US" (United States)
     stateFips : string or iterable of strings, optional
-        Check the `stateFips_lookup()` function in this module for all
-        possible inputs.
+        Call ``get_codes("states")`` for the valid inputs.
         Example: "US:15" (United States: Hawaii)
     countyFips : string or iterable of strings, optional
-        Check the `countyFips_lookup()` function in this module for all
-        possible inputs.
+        Call ``get_codes("counties")`` for the valid inputs.
         Example: "US:15:001" (United States: Hawaii, Hawaii County)
     siteTypeCode : string or iterable of strings, optional
-        An abbreviation for a certain site type. Check the `siteType_lookup()`
-        function in this module for all possible inputs.
+        An abbreviation for a certain site type. Call ``get_codes("sitetype")``
+        for the valid inputs.
         Example: "GW" (Groundwater site)
     siteTypeName : string or iterable of strings, optional
-        A full name for a certain site type. Check the `siteType_lookup()`
-        function in this module for all possible inputs.
+        A full name for a certain site type. Call ``get_codes("sitetype")``
+        for the valid inputs.
         Example: "Well"
     usgsPCode : string or iterable of strings, optional
         5-digit number used in the US Geological Survey computerized
         data system, National Water Information System (NWIS), to
-        uniquely identify a specific constituent. Check the
-        `characteristic_lookup()` function in this module for all possible
-        inputs.
+        uniquely identify a specific constituent (the ``parameterCode`` column
+        of ``get_codes("characteristics")``).
         Example: "00060" (Discharge, cubic feet per second)
     hydrologicUnit : string or iterable of strings, optional
         Max 12-digit number used to describe a hydrologic unit.