User guide¶
Each page covers one part of the package, and its examples run against the live
services. The examples also use packages that water-ogcapi does not install:
With conda:
conda install -c conda-forge water-ogcapi "pyarrow>=24" "pyproj>=3.7" "shapely>=2.1" geopandas polars dask
Read the pages in this order:
- Installation and the API key: installing the package and its
arrowextra, and howWaterDatasends a USGS API key. - Queries and results: collections, the query forms,
QueryResultandPage, and Arrow tables. - Data files from the STAC API:
WaterDataSTAC, its items, and downloading the files they link. - Pagination and large queries:
iter_pages()andcollect(), splitting a WaterData query, converting page by page, and resuming a stopped query. - Errors: what each exception means and what it carries.
- Blocking and async APIs: the blocking classes and their async
twins in
water_ogcapi.aio. - Logging: what the package logs,
configure_logger(), and routing records through an application's own handlers. - Dask and multiprocessing workers: sending a service to worker processes.
- Performance: offline benchmarks of cold start, requests per query, peak memory, 429 recovery, and decoding.
For packages that use the same services,
water-ogcapi as the transport for dataretrieval shows where its
Water Data getters could send their requests through this package, and
Migrating from pynhd.ogcapi maps each pynhd.ogcapi call to its
water-ogcapi equivalent.
The example notebooks walk through each service, and the API reference lists every parameter.