# Stats envelope — one row per spatial unit, three services

`stats-envelope/1` is the shared answer shape of

| service | endpoint | figures |
|---|---|---|
| umfeld-at | `GET https://umfeld-at.exe.xyz/api/v1/ne/stats/unit` | declared · observed · diff · change · subsidy · protection per H3 cell set, **plus the two peers' envelopes for the same unit** |
| srtm-lidar-at | `GET https://srtm-lidar-at.exe.xyz/api/v1/stats/unit` | observed cover, consistency, terrain, heights, canopy, ALS epochs |
| farm-subsidies-austria | `GET https://farm-subsidies-austria.exe.xyz/api/v1/stats/unit` | INVEKOS claims, classes, crops, lineage vs previous year, Gemeinde payments |

Same unit keys, same top level, flat scalar figures, so a spreadsheet row, an agent or a chart reads
any of the three — or all three through umfeld-at — without walking cells.

## 1. Unit keys

```
?kg=63330[,63331…]      5-digit KG code(s), ≤ 50 → one envelope per code ("units":[…] when > 1)
?h3=871e108d9ffffff     H3 cell, res 5–12: every res-12 descendant (the hierarchy is exact here)
?bbox=w,s,e,n           WGS84; cells whose centre lies inside (half-open); span ≤ 0.1°
```
umfeld-at additionally takes the landing page's own keys, so **the share link and the export are one
URL logic** — whatever `#…` a user copies from the map is a valid `share=` and vice versa:
```
?adm=61630              Gemeinde (5 digits, union of its KGs) · ?adm=606 Bezirk · ?adm=AT2205000  Natura 2000 site (centre inside)
?combine=1              several kg= / adm= units as ONE unit, their union (kind "combined", key "kg=a,b;adm=c")
?pt=15.1,47.12          the res-7 cell under a point
?share=%23kg%3D63330%3Bf%3Dforest   the map's hash verbatim (kg= h3= adm= pt= and f= are read, view tokens ignored)
?f=<expr>               the glyph filter (same grammar as /api/v1/ne/filter): figures cover the MATCHING cells,
                        unit_cells_n / unit_area_ha keep the whole unit; the peers are asked for the SAME matching
                        cells (§6 cell list), so srtm.* / sub.* are filtered too
```
**Combined units.** A `share=` naming several areas (`#kg=a,b;adm=c,d` — the map's combined selection) is
ONE unit: the union of their cells. Every cell counts once whatever the overlap — a KG inside a listed
Gemeinde adds nothing, a Natura 2000 site partly inside a listed KG adds only its part outside, two KGs
sharing a border cell hold it whole between them. So `area_ha` of a combination is never the sum of its
members' rows unless they are disjoint. `combine=0` keeps the members apart (one row each, overlaps in each).
A unit holds up to 300 KGs (a Bezirk fits, a Bundesland does not — pass its Bezirke).

**Exact and approximate.** A unit up to 48 bins (0.025°) is answered cell-exact at once; a combined unit is
measured by its members' boxes, not their hull (two small KGs far apart stay exact). A larger unit is
answered at once from the national 1-in-49 sample (`coverage.approx: true`) and, without `f=`, computed
cell-exact in the background: `coverage.exact: "pending"` says so, the answer is not cacheable, and the same
URL returns the exact figures (no `approx`) a minute or so later.

## 2. Envelope

```json
{"schema":"stats-envelope/1","service":"umfeld-at",
 "unit":{"kind":"kg|h3|bbox|gemeinde|bezirk|natura2000|combined","key":"63330","name":"Kohlschwarz","bbox":[w,s,e,n],"res":12,"cells_n":52478,"area_ha":1593.37,"kgs":["63330"]},
 "source":"umfeld-at@ne-fidx1","epoch":"YYYY-MM",
 "coverage":{"complete":true,"cells_known":52478,"cells_total":52478,"bins":12,"bins_missing":0,"note":"…"},
 "filter":{"f":"d=wald","words":"forest","ignored":[],"note":"…"},          ← only with f=
 "figures":{ flat, dotted keys, scalars only — §3 },
 "peers":{"srtm-lidar-at":{ their envelope },"farm-subsidies-austria":{ their envelope }},   ← umfeld-at only
 "attribution":"…","license":"CC-BY-4.0","computed_at":"YYYY-MM-DDThh:mm:ssZ","age_s":0,
 "link":"https://umfeld-at.exe.xyz/#kg=63330"}
```
Rules every service keeps: `figures` is **flat** (dotted keys), values are `number | string | bool | null`;
the unit is in the key suffix (`_ha _n _m _deg _pct _eur _year`); no data → `200` with
`coverage.complete=false` and empty figures (rows never break); `area_ha` and `cells_n` mean the same
thing everywhere (umfeld-at and the observed-layer peer agree cell for cell on `kg=` and `h3=` — same res-12 set, border
cells weighted by the KG share; farm-subsidies-austria clips its own polygons, so its `area_ha` is the unit
polygon's, not a cell sum).

## 3. umfeld-at figures

```
cells_n area_ha cells_declared_n cells_observed_n            [unit_cells_n unit_area_ha match_pct with f=]
declared_ha.<geb|bau|acker|gruen|wald|wasser|verkehr|alpen|sonst|undeclared>  declared.dominant     share-weighted from the declared view (log → bev → lu)
observed_ha.<same groups|unknown>                                                               share-weighted from the peer's observed rows
diff_ha.<consistent|forest_loss|forest_gain|sealed_new|structure_new|green_new|unknown>  diff.consistent_pct    register vs LiDAR, per cell today
change_n.<none|candidate|confirmed>  change_ha.<same>  change.log_versions  change.log_since   the register over time (confirmed = digest seen twice)
subsidy_ha.<acker|gruenland|alm|wein|dauerkultur|gloez|sonst>  subsidy.claimed_ha .claimed_pct .bio_ha .bio_pct .known_pct   INVEKOS class × claimed share per cell
natura2000_ha natura2000_pct  structures_n structures.cover_ha
terrain.elev_mean_m terrain.slope_mean_deg height.p90_mean_m canopy.cover_pct ndvi.mean       area-weighted means over cells with a value
trees_n                                              tree apices (≥ 3 m) of the counted cells; under a height term (ht=, htmax=, hc=) only the apices inside it — absent when a cell had no apex list
kg.dominant kg.n kg.name gemeinde.code gemeinde.name bezirk.name bundesland.name             where the unit sits (h3 / bbox / Natura: the dominant KG)
```
Every per-cell number comes from the filter index bins (`/api/v1/ne/glyph/fidx`) joined with the cells'
declared/observed rows — `/api/v1/ne/filter`, the map's filter chips and this endpoint count the same
cells (exact H3 centres, exact cell areas).

Peer envelopes are passed through unchanged under `peers.<service>`. For a Gemeinde the peers answer
per KG; umfeld-at sums their additive figures (`_ha _n _eur`), recomputes `_pct` from `area_ha` and
drops means, codes and names (`coverage.note` says so; `units_n` counts the members).

## 4. Formats

```
format=json   the envelope (default); several units → {"schema","service","units":[…]}
format=flat   ONE flat object: unit.kind unit.key unit.name unit.bbox coverage.complete [filter] <figures> srtm.<key> sub.<key> link
format=csv    header row + one row per unit (text/csv, UTF-8, no BOM); every answer carries a telling file name (unit, filter, day); &download=1 makes it a download
keys=a,b      only these keys (prefix match: keys=declared_ha,srtm.cover_ha,sub.claimed)
peers=srtm,sub|none   which peers to ask (default both; none with f=)      year=   passed to farm-subsidies-austria
```
Google Sheets: `=IMPORTDATA("https://umfeld-at.exe.xyz/api/v1/ne/stats/unit?kg=63330&format=csv")`
(the map's ▾ next to the link button copies this formula for the current view). Excel: Power Query →
From Web, same URL. Several KGs in one sheet: `kg=63330,63331,…` → one row each.

Caching: `ETag`, `Cache-Control: max-age=600` (`no-store` while a bin is still building or a peer was
down), CORS `*`, gzip. First call on a cold area builds the index bins (seconds; a Gemeinde up to a
minute); afterwards milliseconds. Answers carry standard `RateLimit-*` headers.

## 5. Peer envelopes

Both peers answer the same keys (`h3= kg= bbox=`, and a cell list, §6) with the same envelope, `format=json|flat|csv`,
`keys=`, and an unknown unit → 200 with `coverage.complete=false`. The observed-layer peer
(srtm-lidar-at) carries `source "srtm-lidar-at@<version>"`, `unit.res 12`, `unit.cells_n`, shared
`cover_ha.<geb..sonst>`, `consistency_ha/_n.<verdict>`, terrain, heights and `als.*`. The subsidy
peer (farm-subsidies-austria) carries `source "invekos@<release>"`, `epoch` = claim year, `class_ha.<cls>`,
`top_snar.<1..5>.*`, `lineage_ha.<…>` and `gemeinde.*` from the Transparenzdatenbank (dominant
Gemeinde + `gemeinde.n` for units spanning several). umfeld-at calls them with a 5 s timeout,
≤ 2 req/s, memoised 10 min; a peer that is down shows as `peers.<service>.available=false` and the
row keeps the other columns.

## 6. Cell lists — a filtered unit at the peers

With `f=` umfeld-at knows the matching cells and the peers do not (the grammar spans all three
services' columns). So the peers are asked for an explicit cell set instead of a unit key:

```
POST {peer}/api/v1/stats/unit?format=json&unit=cells[&scale=49][&year=]
Content-Type: application/octet-stream · Content-Encoding: gzip
body (gzip'd):  "NEI1" · u32 n · n × u64 little-endian H3 res-12 cell ids, sorted ascending
```
The answer is the ordinary envelope over exactly those cells: `unit.kind="cells"`, `unit.key` =
a short hash of the list, `unit.cells_n` = n × scale, `unit.area_ha` = Σ cell areas × scale, every
`_ha`/`_n` figure summed over the listed cells (× `scale`), means and `_pct` unweighted by scale.
`scale` is 49 when the list is the national 1-in-49 sample (one res-12 cell per res-10 cell —
each listed cell stands for its 48 siblings; the peer may read the siblings' own rows instead of
multiplying if it prefers). Unknown cells are counted in `coverage.cells_known` only when the peer
holds a row; the border weighting of `kg=` does not apply (every listed cell counts 1). Limits:
≤ 1 M ids (8 MB raw), the usual rate limits. Ids are unique (duplicates are a client bug; peers
may drop them). A peer that needs time for a large list may answer `202` with
`{"status":"computing","retry_after_s":N}` and a `Retry-After` header; umfeld-at re-POSTs the same
body after that delay for up to ~25 s — or, when the 202 carries `unit.key`, polls
`GET …?unit=cells&key=<unit.key>[&scale=][&year=]` instead (same 200/202 answers, no re-upload;
a 400/404/405 on that form falls back to re-POSTing) — then reports `available=false` with
"still computing … retry in Ns" (a later call picks up the finished answer). A peer that does not
support cell lists answers 404/405/415 and umfeld-at reports `peers.<service>.available=false`
with the reason — it never substitutes the whole-unit envelope for a filtered one.
