Overview

The USGS Geo Data Portal (GDP) exposes gridded climate and meteorological data through a pygeoapi server at https://api.water.usgs.gov/gdp/pygeoapi. The service implements several complementary OGC API standards, each suited to different access patterns:

• OGC API – EDR — lightweight queries for values at a specific location or small spatial extent, useful when a full Zarr-capable environment is not needed
• STAC catalog — dataset discovery and cloud-native access for larger or more complex workflows where tools like xarray, Dask, or Zarr are available
• OGC API – Processes — server-side geoprocessing (area-weighted statistics, spatial interpolation) powered by gdptools

If you are new to OGC API: it is a family of RESTful standards that replace older OGC services (WMS, WFS, WCS) with modern JSON/HTTP patterns. Every endpoint returns standard JSON by default and supports content negotiation via a ?f= parameter — more on that below.

EDR — Small-Scale Data Access

OGC API – Environmental Data Retrieval (EDR) is a standard for querying environmental data by geographic position or spatial extent. Use it when you need to extract values at a point or within a bounding box and a full Zarr-capable data environment is not warranted.

The GDP EDR collections are gridded CONUS datasets covering precipitation, temperature, wind speed, evapotranspiration, and hydrological model output. Browse the current list at /collections .

This service supports two EDR query types:

• Position (/collections/{id}/position) — extract values at a single coordinate (longitude, latitude) over a time range
• Cube (/collections/{id}/cube) — extract values within a bounding box and time range

See the OGC API – EDR specification for the full standard.

STAC Catalog — Data Discovery and Larger Workflows

The SpatioTemporal Asset Catalog (STAC) interface provides searchable metadata for a broad collection of water-related datasets — climate models, downscaled projections, evapotranspiration, land cover, and more. Use it when you need to discover datasets and access data in bulk or via cloud-native formats (Zarr, COG) in environments with xarray, Dask, or similar tooling.

The STAC catalog is not linked from the JSON landing page. Access it directly at /stac .

See the STAC specification for the full standard.

OGC API – Processes and gdptools

The Processes endpoint exposes server-side geoprocessing via the OGC API – Processes standard.

These processes are underpinned by gdptools , a Python package for calculating area-weighted statistics and spatial interpolations between gridded datasets and vector geometries. Key capabilities include:

• Grid-to-polygon aggregation — aggregate raster data over polygon boundaries
• Grid-to-line interpolation — sample gridded data along vector paths
• Polygon-to-polygon transfer — convert data between spatial frameworks with proper handling of extensive vs. intensive variables

Processes run asynchronously: submit a job to /processes/{id}/execution, poll for status at /jobs/{jobId}, and retrieve results when complete.

Browse available processes at /processes .

Using the Built-In Developer Tools

The HTML views that pygeoapi generates are not a user interface — they are browser-based API introspection tools intended for developers during integration and testing. They render the same data the JSON API returns, formatted for human reading.

Every endpoint supports a ?f= parameter for content negotiation:

• ?f=json — machine-readable JSON (default for programmatic access)
• ?f=html — human-readable HTML view (auto-generated by pygeoapi)

Useful developer entry points:

• Swagger UI — /openapi?f=html — interactive endpoint testing; try queries and inspect request/response shapes
• HTML collection browser — append ?f=html to any endpoint (e.g. /collections/PRISM?f=html ) to browse metadata and query options
• STAC HTML view — /stac?f=html — browse the full dataset catalog

Key Endpoints

All paths are relative to https://api.water.usgs.gov/gdp/pygeoapi.

Related Use Cases

Worked examples demonstrating GDP pygeoapi workflows are available at water.usgs.gov/catalog/usecases :

• Environmental Data Retrieval (EDR) — accessing spatio-temporal data via the EDR API
• WMA STAC Catalog — discovering and reading STAC assets into a Python workflow
• Asynchronous Processing via OGC API Processes — executing gdptools processes asynchronously via pygeoapi
• gdptools + CONUS404 — spatially aggregating CONUS404 data to HUC12 polygons
• Regridding gridMET to HUC12s — area-weighted climate forcing aggregation
• Dockerized pygeoapi Deployment — deploying custom data services through pygeoapi

Notes & TODOs

• TODO: Add example EDR position and cube query URLs with parameter values
• TODO: Document specific gdptools processes available at /processes
• TODO: Cross-link to notebooks once authored
• TODO: Clarify relationship between EDR collections and STAC collections