Zone Data

The richest endpoint in the API: field values for a zone (and optionally its child zones), from one collection, an arbitrary raster, or several collections joined together. Three request shapes share this route.

Collection-backed: `GET /collections/{collection_id}/dggs/{dggrs_id}/zones/{zone_id}/data`


curl "https://api.geoinsight.ai/collections/{collection_id}/dggs/isea3h/zones/{zone_id}/data"

‌

Behavior depends on how the collection is backed:

DuckDB-backed (DataAccess::DuckDb) — values come from the parquet lake, aggregated per zone.
Direct raster URL (DataAccess::Url) — zonal statistics computed on that fixed COG.
STAC-backed (DataAccess::Stac) — the API searches the collection’s STAC catalog for the item(s) covering the zone (see stac-search-strategy below) and computes zonal statistics on the matched raster(s).
OGC API Features (DataAccess::OgcApiFeat) — values come from a proxied OGC Features backend.

Query parameters

Param	Description
`zone-depth`	Relative depth of child zones to aggregate into the response — a single value (`1`) or a list (`1,2`). Defaults to the DGGRS’s default depth.
`datetime`	RFC 3339 instant or interval (`../` open-ended) filtering temporal sources.
`properties`	Comma-separated field names to include. Omit for all queryables.
`exclude-properties`	Comma-separated field names to drop, applied after `properties`.
`refined-geometry`	Densify returned geometry. Default `false` here (unlike the zone geometry route, which defaults to `true`).
`f`	`json` / `dggs+json` (default, DGGS-JSON), `geo+json`, `html`, `parquet`, `geoparquet`.

Raster-only, collection-level overridable via cog-* params (see below): stac-search-strategy, intersection_percent, cloud_cover_percent.

Ad-hoc raster: `GET /dggs/{dggrs_id}/zones/{zone_id}/data?cog-url=...`

No collection — query any Cloud-Optimized GeoTIFF directly by URL.


curl "https://api.geoinsight.ai/dggs/isea3h/zones/{zone_id}/data?cog-url=https://example.com/raster.tif&cog-stat=mean,max"

‌

Param	Description
`cog-url`	Required on this route. The COG to read.
`cog-stat`	Comma-separated: `count`, `valid`, `min`, `max`, `mean`, `median`. Default `mean`.
`cog-band`	Comma-separated 1-based band indices. Default `1`.
`cog-no-data-value`	Override the raster’s no-data value.
`cog-sampling-factor`	Sampling density relative to zone count. Default `8.0`.
`cog-all-touched`	Include pixels only touched (not fully covered) by the zone polygon. Default `false`.

Calling this route with neither a /collections/{id} path segment nor cog-url returns a 400 telling you to either add one or POST a cross-collection body (next section).

Cross-collection: `POST /dggs/{dggrs_id}/zones/{zone_id}/data`

Reads selected fields from several collections for one zone and joins them into a single wide table, keyed on zone_id. Output columns are named {prefix}__{field}, where prefix is a selection’s alias or its collection id.


curl -X POST "https://api.geoinsight.ai/dggs/isea3h/zones/{zone_id}/data" \
  -H "Content-Type: application/json" \
  -d '{
    "collections": [
      { "id": "landcover", "fields": ["class", "water"] },
      { "id": "elevation", "fields": ["mean"], "filter": "mean > 0" }
    ]
  }'

‌

Each entry in collections:

Field	Description
`id`	Collection to read from.
`fields`	Required, non-empty — no wildcard, so the response shape never changes silently when a collection’s schema gains a field.
`alias`	Overrides `id` as the output column prefix. Needed to select the same collection twice under different filters.
`filter`	A CQL2 predicate (text or JSON) restricting source rows. Only DuckDB-backed collections support this.

Non-collection query params (f, zone-depth, datetime, refined-geometry) still work as query params on the POST — everything collection-specific moves into the body. properties, exclude-properties, and cog-url are rejected on this route (400): field selection happens per-collection in the body instead.

Response shape

DGGS-JSON (the default / f=dggs+json / f=json) returns:


{
  "dggrs": "[ogc-dggrs:isea3h]",
  "zoneId": "...",
  "defaultDepth": 0,
  "depths": [0],
  "data": { "...": "one row per resolved zone, one value per requested field" },
  "zones": [ /* zone geometries, per zone-depth */ ],
  "links": [ /* including a source link back to the underlying STAC item / URL, where applicable */ ]
}

f=geo+json wraps the same values as a GeoJSON FeatureCollection; f=html renders a table; f=parquet/f=geoparquet return the page as a file download.