Skip to content

Installation and the API key

Installation

Install from PyPI or conda-forge (Python 3.12 or later):

pip install water-ogcapi
conda install -c conda-forge water-ogcapi

The arrow extra adds pyarrow, shapely, and pyproj for the to_arrow() methods:

pip install "water-ogcapi[arrow]"

conda-forge packages have no extras, so a conda install names the three packages:

conda install -c conda-forge water-ogcapi "pyarrow>=24" "pyproj>=3.7" "shapely>=2.1"

The development version installs from GitHub:

pip install git+https://github.com/hyriver/water-ogcapi

The core installs two runtime dependencies, httpx2 and h2, and imports no frame library. pandas, geopandas, and polars read the tables that to_arrow() returns, and none of them is a dependency.

The USGS API key

WaterData works without a key. The USGS Water Data API keys page explains the hourly limits a key raises and issues one. Set it in the environment:

export USGS_API_KEY="your key"

WaterData() reads USGS_API_KEY once, when it is built. WaterData(api_key=...) takes the key from code, and WaterData(api_key="") sends none. The key travels only in the X-Api-Key header of each request, never in a URL, so it stays out of the next links the server writes and out of every Page.url. FabricData and GeoConnex never receive it.

Keyed WaterData responses report the key's quota in their X-RateLimit-Limit and X-RateLimit-Remaining headers, which Page.headers keeps. Unkeyed WaterData responses carry neither header, so both read None below without a key:

import os

from water_ogcapi import WaterData

print("key set:", bool(os.environ.get("USGS_API_KEY")))
with WaterData() as wd:
    page = wd.item("monitoring-locations", "USGS-01646500")
print(page.headers.get("x-ratelimit-limit"), page.headers.get("x-ratelimit-remaining"))

A key passed in params raises before any request is sent, since a query parameter would put it in the URL:

from water_ogcapi.exceptions import ValidationError

with WaterData() as wd:
    try:
        wd.collect("monitoring-locations", params={"api_key": "not-a-key"})
    except ValidationError as err:
        print(err)

Pacing

Each service paces its own requests. It spaces them further apart as X-RateLimit-Remaining runs down, and one second apart when responses carry no rate-limit headers, as GeoConnex's and unkeyed WaterData responses do. A timeout, a failed connection, read, or write, or a 429, 500, 502, 503, or 504 response is retried up to three times. A proxy refusal, an unsupported URL scheme, or a request httpx2 cannot encode raises at once. A Retry-After of up to 60 seconds sets the wait. A longer one raises at once, as a RateLimitError for a 429, with the wait in its retry_after. Transport(max_retries=...) changes the retry count:

from water_ogcapi import Transport

with WaterData(transport=Transport(max_retries=1)) as wd:
    page = wd.item("monitoring-locations", "USGS-01646500")
print(page.status)