Add waterdata infrastructure

[ehinman]

This PR will add access to the new water data APIs via the waterdata module.

9/26/25: Added some updates to the README.md about the new module and API keys. Ready for testing and review.

EOD 9/25/25: qualifier is a tricky argument and product owner suggests against using it as an argument unless you're really confident and restrictive about what you want: it can be a list of multiple qualifiers and if you just pick one qualifier value, it will only match rows with JUST that one. Default is to return a geopandas dataframe when geometry are returned, but because geopandas is an optional dependency, functions will return pandas dataframes if geopandas is not available. Unit tests have been created, with opportunities for more. I'd say the functions are ready for testing. I need to add in some info on the new functions in the README, etc.

9/25/25: POST calls using the CQL2 query language appear to be working, and documentation for the functions has been added. I'm noticing some inconsistencies in some of the input parameters like qualifier that still need to be addressed/parsed. I also need to create unit tests and I'd like to have the functions return a geopandas dataframe when skipGeometry=False.

9/19/25: It is currently a work in progress that appears to work for GET calls in which the user requests one parameter (e.g. one site, one pcode, etc.) at a time. Still working out the POST calls in which a user may request multiple parameters (e.g. data from multiple sites, with multiple pcodes), which requires the use of the CQL2 query language. Stay tuned.

[agilmore2]

how do we pass the api_key API parameter here?

[ehinman]

I will add documentation about this (still learning the details myself), but your API key should be passed as a header if it exists as an environment variable. This is the line used to grab the api key in one of the helper functions:
token = os.getenv("API_USGS_PAT")

So you'll want to get your API key, and then set it using:

os.environ["API_USGS_PAT"] = "<your key>"

You may need to restart your session to get it to "register".

[ehinman]

And to be clear: all you need to do is have your key in your environment, you don't need to "set it" in the functions anywhere.

[agilmore2]

Understood, thanks! I was pulling it out of an environment variable myself and expecting to set it in the retrieval functions, but the functions pulling it themselves also works. I appreciate your hard work on these!

…

On Thu, Sep 25, 2025, 08:25 Elise Hinman ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In dataretrieval/waterdata.py <#183 (comment)> : > + parameter_code: Optional[Union[str, List[str]]] = None, + statistic_id: Optional[Union[str, List[str]]] = None, + properties: Optional[List[str]] = None, + time_series_id: Optional[Union[str, List[str]]] = None, + daily_id: Optional[Union[str, List[str]]] = None, + approval_status: Optional[Union[str, List[str]]] = None, + unit_of_measure: Optional[Union[str, List[str]]] = None, + qualifier: Optional[Union[str, List[str]]] = None, + value: Optional[Union[str, List[str]]] = None, + last_modified: Optional[str] = None, + skipGeometry: Optional[bool] = None, + time: Optional[Union[str, List[str]]] = None, + bbox: Optional[List[float]] = None, + limit: Optional[int] = None, + max_results: Optional[int] = None, + convertType: bool = True I will add documentation about this (still learning the details myself), but your API key should be passed as a header if it exists as an environment variable. This is the line used to grab the api key in one of the helper functions: token = os.getenv("API_USGS_PAT") So you'll want to get your API key, and then set it using: os.environ["API_USGS_PAT"] = "<your key>" You may need to restart your session to get it to "register". — Reply to this email directly, view it on GitHub <#183 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABUI5SVU5QEID6FDYDBVEHL3UP3M7AVCNFSM6AAAAACHAHDID6VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTENRYGA2DAOBUHA> . You are receiving this because you commented.Message ID: ***@***.***>

[agilmore2]

I see that in _default_headers() Thanks!

…

On Thu, Sep 25, 2025 at 8:32 AM Elise Hinman ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In dataretrieval/waterdata.py <#183 (comment)> : > + parameter_code: Optional[Union[str, List[str]]] = None, + statistic_id: Optional[Union[str, List[str]]] = None, + properties: Optional[List[str]] = None, + time_series_id: Optional[Union[str, List[str]]] = None, + daily_id: Optional[Union[str, List[str]]] = None, + approval_status: Optional[Union[str, List[str]]] = None, + unit_of_measure: Optional[Union[str, List[str]]] = None, + qualifier: Optional[Union[str, List[str]]] = None, + value: Optional[Union[str, List[str]]] = None, + last_modified: Optional[str] = None, + skipGeometry: Optional[bool] = None, + time: Optional[Union[str, List[str]]] = None, + bbox: Optional[List[float]] = None, + limit: Optional[int] = None, + max_results: Optional[int] = None, + convertType: bool = True And to be clear: all you need to do is have your key in your environment, you don't need to "set it" in the functions anywhere. — Reply to this email directly, view it on GitHub <#183 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABUI5SSOIKUSVNDVU3D7QVD3UP4IXAVCNFSM6AAAAACHAHDID6VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTENRYGA4DINBSGY> . You are receiving this because you commented.Message ID: ***@***.***>

[thodson-usgs]

We want to keep geopandas as an optional dependency, I think. See the nldi module for example.