Blocking and async APIs¶
Blocking classes¶
WaterData, WaterDataSTAC, FabricData, GeoConnex, and OGCService at the package
root block until each call returns. Each one owns an async service of its own and runs
it on one background event-loop thread that the package starts on first use. A call from
any thread, a Jupyter cell included, waits for that loop and never calls
asyncio.run(), so it works where another event loop is already running.
iter_pages() returns a plain iterator. Each step fetches one page, and closing the
iterator, or dropping it, stops the query:
from water_ogcapi import WaterData
DC = (-77.12, 38.80, -76.91, 38.99)
with WaterData() as wd:
pages = wd.iter_pages("monitoring-locations", bbox=DC, params={"limit": "100"})
first = next(pages)
pages.close()
print(first.feature_count, "features in the first page")
Async classes¶
water_ogcapi.aio holds the async twins, with the same names and arguments. Use them
from code that runs its own event loop, and to run several queries concurrently on one
service:
import asyncio
from water_ogcapi.aio import WaterData as AsyncWaterData
SITES = ["USGS-01646500", "USGS-01594440", "USGS-01638500"]
QUERY = {"parameter_code": "00060", "statistic_id": "00003", "datetime": "2025-06-01/2025-06-30"}
async def main() -> None:
async with AsyncWaterData() as wd:
results = await asyncio.gather(
*(
wd.collect("daily", params={**QUERY, "monitoring_location_id": site})
for site in SITES
)
)
async for page in wd.iter_pages("monitoring-locations", bbox=DC, params={"limit": "100"}):
print(page.feature_count, "features")
break
for site, result in zip(SITES, results, strict=True):
print(site, len(result.geojson["features"]), "days")
asyncio.run(main())
One service shares its transport, quota pacing, and metadata cache across every query it
runs, so the three queries above draw on one pacing schedule. The transport runs up to
max_per_origin requests at once to one host, 4 by default, and up to max_concurrent
across all hosts, 16 by default.
Transports¶
Transport holds the HTTP client and its settings: timeout per attempt (30 seconds),
max_concurrent, max_per_origin, max_retries, and backoff. One request(),
get(), or download() call can set its own timeout= and max_retries=. A service
builds a transport unless given one. A transport binds to the event loop of its first
request, so share one only among blocking services, which all run on the background
loop, or only among async services on one loop:
from water_ogcapi import FabricData, Transport
transport = Transport(timeout=60, max_concurrent=2)
wd = WaterData(transport=transport)
fabric = FabricData(transport=transport)
print(len(wd.collect("monitoring-locations", bbox=DC).geojson["features"]))
print(len(fabric.collect("gagesii", bbox=DC).geojson["features"]))
wd.close()
close() on either service closes the shared transport, and the other reconnects on its
next request.
Plain HTTP from sync code¶
Client sends any request from blocking code through one Transport on the background
loop. get(), request(), and download() each send one request. To send many at
once, write a coroutine that gathers Transport calls and pass it to run(), which
runs it on the same loop and returns what it returns:
import asyncio
from water_ogcapi import Client
NLDI = "https://api.water.usgs.gov/nldi/linked-data/comid"
COMIDS = [1722317, 1722211, 1722207]
with Client() as client:
async def fetch_all() -> list:
return await asyncio.gather(*(client.transport.get(f"{NLDI}/{c}") for c in COMIDS))
responses = client.run(fetch_all())
print([response.status for response in responses])
Pass the coroutine object, fetch_all(). run() refuses a coroutine function, a
future, or a task, so call asyncio.gather() inside the coroutine: the future it
returns belongs to the loop that made it. An interrupt, such as stopping a notebook
cell, cancels the coroutine and every request it gathered; the cancellation finishes on
the loop after the interrupt reaches your code.