Skip to content

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:

pip install "water-ogcapi[arrow]" geopandas polars "dask[distributed]"

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:

  1. Installation and the API key: installing the package and its arrow extra, and how WaterData sends a USGS API key.
  2. Queries and results: collections, the query forms, QueryResult and Page, and Arrow tables.
  3. Data files from the STAC API: WaterDataSTAC, its items, and downloading the files they link.
  4. Pagination and large queries: iter_pages() and collect(), splitting a WaterData query, converting page by page, and resuming a stopped query.
  5. Errors: what each exception means and what it carries.
  6. Blocking and async APIs: the blocking classes and their async twins in water_ogcapi.aio.
  7. Logging: what the package logs, configure_logger(), and routing records through an application's own handlers.
  8. Dask and multiprocessing workers: sending a service to worker processes.
  9. 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.