Distributions and summary statistics for a zoning category in a commune

Returns the per-parcel metric distributions, summary statistics, age cohorts, and raw scatter inputs that drive the room Aireon app. Backed by an in-memory LRU keyed on ${fso}:${cz_local} (capacity 500, TTL 1 hour).

Server-side rules:

Nulls are dropped before computing distributions and summary.
Hard outliers (above p99.5 or below p0.5 within the zone) are trimmed from distributions[*]; raw min/max stay in summary.
parcels[] is unfiltered.
other_zones lists every distinct cz_local in the same FSO except the queried one, sorted by parcel count desc.

GET alias (cacheable). Identical handler and identical response to the POST, with the inputs as query parameters. A POST is uncacheable by browsers and by any CDN, so apps on a first-load path should prefer this GET.

The response carries Cache-Control: private, max-age=86400, stale-while-revalidate=21600 and Vary: Origin, token. The policy is private, never public: the endpoint is gated on the token request header, and a header is not part of any shared-cache key - a public/s-maxage directive would let a CDN serve the payload to a caller that never presented the token. Error responses (including the legacy HTTP-200 plain-text ones) carry Cache-Control: no-store.

Snapshot and revalidation. Every 200 carries X-Res-Snapshot (the identity of the serving data the payload is computed from: the serving table, plus the last completed serving refresh when recorded, e.g. parcel_2025_07@20261020T031200Z) and a strong ETag derived from the snapshot, the payload version, fso, zone and lang (never from the body). Send it back as If-None-Match and a match answers 304 before any computation runs, token required. Pass snapshot=<value> to pin the data version: when it is not the current snapshot the answer is 409 {"error":"snapshot_mismatch","snapshot":<current>} with Cache-Control: no-store.

GET

https://res.aireon.ch/res_api/zone_stats

Authorization

ResApiToken
API key in header
required

Query parameters

fso
optional
integer
BFS/OFS commune number. Required.
zone
optional
string
Local construction-zone label (cz_local). Required (as zone or cz_local); zone wins when both are sent.
cz_local
optional
string
Alias of zone.
snapshot
optional
string
Optional pin: the X-Res-Snapshot value the caller expects. A different current snapshot answers 409.
lang
optional
string
Echoed back as _lang; does not change the data.

Returns

200

Zone statistics payload.

JSON

zone
object
required
- fso
  integer
  required
- cz_local
  string
  required
- parcel_count
  integer
  required
- municipality_name
  optional
  string | null
- cz_canton
  optional
  string | null
}
other_zones
array of
object
required
Sibling cz_local values in the same FSO, sorted by parcel count desc.
- cz_local
  string
  required
- parcel_count
  integer
  required
}
distributions
object
required
Trimmed (p0.5–p99.5) per-parcel samples for each metric.
- ratio_s
  optional
  array of
  number
- gfz
  optional
  array of
  number
- bldg_height_m
  optional
  array of
  number
- bldg_floors_n
  optional
  array of
  number
}
summary
object
required
- ratio_s
  optional
  object
  Summary statistics for one metric across the zone. Computed on the raw (non-trimmed) sample; min/max are honest to the underlying data.
  
  n
  integer
  required
  min
  optional
  number | null
  max
  optional
  number | null
  p5
  optional
  number | null
  p25
  optional
  number | null
  p50
  optional
  number | null
  p75
  optional
  number | null
  p95
  optional
  number | null
  mean
  optional
  number | null
- gfz
  optional
  object
  Summary statistics for one metric across the zone. Computed on the raw (non-trimmed) sample; min/max are honest to the underlying data.
  
  n
  integer
  required
  min
  optional
  number | null
  max
  optional
  number | null
  p5
  optional
  number | null
  p25
  optional
  number | null
  p50
  optional
  number | null
  p75
  optional
  number | null
  p95
  optional
  number | null
  mean
  optional
  number | null
- bldg_height_m
  optional
  object
  Summary statistics for one metric across the zone. Computed on the raw (non-trimmed) sample; min/max are honest to the underlying data.
  
  n
  integer
  required
  min
  optional
  number | null
  max
  optional
  number | null
  p5
  optional
  number | null
  p25
  optional
  number | null
  p50
  optional
  number | null
  p75
  optional
  number | null
  p95
  optional
  number | null
  mean
  optional
  number | null
- bldg_floors_n
  optional
  object
  Summary statistics for one metric across the zone. Computed on the raw (non-trimmed) sample; min/max are honest to the underlying data.
  
  n
  integer
  required
  min
  optional
  number | null
  max
  optional
  number | null
  p5
  optional
  number | null
  p25
  optional
  number | null
  p50
  optional
  number | null
  p75
  optional
  number | null
  p95
  optional
  number | null
  mean
  optional
  number | null
}
age_cohorts
object
required
Mean, p50 and p80 of cz_util_now (utilization) per building-age cohort, widest window first. Seven precision steps: the all-years baseline plus six trailing windows (60/40/20/15/10/5 years). The 15/10/5 steps were added 2026-08-24. Windows are relative to the current year. Each cohort carries n - the narrower the window the thinner the sample, so read n before trusting a cohort mean.
- now
  optional
  object
  One age cohort of the zone, on utilization: the mean, p50 and p80 of cz_util_now (gfa_now / parcel_area, the floor-area utilization) over the same parcels, with n_cz_util_now as their sample size. mean_cz_util_now was added in v0.0.323. The deprecated mean_ratio_v (not utilization) was removed in v0.0.324.
  
  cohort_label
  string
  required
  n
  integer
  required
  p50_cz_util_now
  optional
  number | null
  Median cz_util_now (gfa_now / parcel_area) of the cohort, percentile_cont(0.5). Null when n_cz_util_now is 0.
  
  p80_cz_util_now
  optional
  number | null
  80th percentile of cz_util_now of the cohort, percentile_cont(0.8). Null when n_cz_util_now is 0.
  
  n_cz_util_now
  optional
  integer
  Parcels in the cohort with a usable cz_util_now (the sample behind the mean and the two percentiles).
  
  mean_cz_util_now
  optional
  number | null
  Mean cz_util_now (gfa_now / parcel_area) of the cohort, over the same rows as the percentiles (weight: n_cz_util_now). Null when n_cz_util_now is 0.
- last60
  optional
  object
  One age cohort of the zone, on utilization: the mean, p50 and p80 of cz_util_now (gfa_now / parcel_area, the floor-area utilization) over the same parcels, with n_cz_util_now as their sample size. mean_cz_util_now was added in v0.0.323. The deprecated mean_ratio_v (not utilization) was removed in v0.0.324.
  
  cohort_label
  string
  required
  n
  integer
  required
  p50_cz_util_now
  optional
  number | null
  Median cz_util_now (gfa_now / parcel_area) of the cohort, percentile_cont(0.5). Null when n_cz_util_now is 0.
  
  p80_cz_util_now
  optional
  number | null
  80th percentile of cz_util_now of the cohort, percentile_cont(0.8). Null when n_cz_util_now is 0.
  
  n_cz_util_now
  optional
  integer
  Parcels in the cohort with a usable cz_util_now (the sample behind the mean and the two percentiles).
  
  mean_cz_util_now
  optional
  number | null
  Mean cz_util_now (gfa_now / parcel_area) of the cohort, over the same rows as the percentiles (weight: n_cz_util_now). Null when n_cz_util_now is 0.
- last40
  optional
  object
  One age cohort of the zone, on utilization: the mean, p50 and p80 of cz_util_now (gfa_now / parcel_area, the floor-area utilization) over the same parcels, with n_cz_util_now as their sample size. mean_cz_util_now was added in v0.0.323. The deprecated mean_ratio_v (not utilization) was removed in v0.0.324.
  
  cohort_label
  string
  required
  n
  integer
  required
  p50_cz_util_now
  optional
  number | null
  Median cz_util_now (gfa_now / parcel_area) of the cohort, percentile_cont(0.5). Null when n_cz_util_now is 0.
  
  p80_cz_util_now
  optional
  number | null
  80th percentile of cz_util_now of the cohort, percentile_cont(0.8). Null when n_cz_util_now is 0.
  
  n_cz_util_now
  optional
  integer
  Parcels in the cohort with a usable cz_util_now (the sample behind the mean and the two percentiles).
  
  mean_cz_util_now
  optional
  number | null
  Mean cz_util_now (gfa_now / parcel_area) of the cohort, over the same rows as the percentiles (weight: n_cz_util_now). Null when n_cz_util_now is 0.
- last20
  optional
  object
  One age cohort of the zone, on utilization: the mean, p50 and p80 of cz_util_now (gfa_now / parcel_area, the floor-area utilization) over the same parcels, with n_cz_util_now as their sample size. mean_cz_util_now was added in v0.0.323. The deprecated mean_ratio_v (not utilization) was removed in v0.0.324.
  
  cohort_label
  string
  required
  n
  integer
  required
  p50_cz_util_now
  optional
  number | null
  Median cz_util_now (gfa_now / parcel_area) of the cohort, percentile_cont(0.5). Null when n_cz_util_now is 0.
  
  p80_cz_util_now
  optional
  number | null
  80th percentile of cz_util_now of the cohort, percentile_cont(0.8). Null when n_cz_util_now is 0.
  
  n_cz_util_now
  optional
  integer
  Parcels in the cohort with a usable cz_util_now (the sample behind the mean and the two percentiles).
  
  mean_cz_util_now
  optional
  number | null
  Mean cz_util_now (gfa_now / parcel_area) of the cohort, over the same rows as the percentiles (weight: n_cz_util_now). Null when n_cz_util_now is 0.
- last15
  optional
  object
  One age cohort of the zone, on utilization: the mean, p50 and p80 of cz_util_now (gfa_now / parcel_area, the floor-area utilization) over the same parcels, with n_cz_util_now as their sample size. mean_cz_util_now was added in v0.0.323. The deprecated mean_ratio_v (not utilization) was removed in v0.0.324.
  
  cohort_label
  string
  required
  n
  integer
  required
  p50_cz_util_now
  optional
  number | null
  Median cz_util_now (gfa_now / parcel_area) of the cohort, percentile_cont(0.5). Null when n_cz_util_now is 0.
  
  p80_cz_util_now
  optional
  number | null
  80th percentile of cz_util_now of the cohort, percentile_cont(0.8). Null when n_cz_util_now is 0.
  
  n_cz_util_now
  optional
  integer
  Parcels in the cohort with a usable cz_util_now (the sample behind the mean and the two percentiles).
  
  mean_cz_util_now
  optional
  number | null
  Mean cz_util_now (gfa_now / parcel_area) of the cohort, over the same rows as the percentiles (weight: n_cz_util_now). Null when n_cz_util_now is 0.
- last10
  optional
  object
  One age cohort of the zone, on utilization: the mean, p50 and p80 of cz_util_now (gfa_now / parcel_area, the floor-area utilization) over the same parcels, with n_cz_util_now as their sample size. mean_cz_util_now was added in v0.0.323. The deprecated mean_ratio_v (not utilization) was removed in v0.0.324.
  
  cohort_label
  string
  required
  n
  integer
  required
  p50_cz_util_now
  optional
  number | null
  Median cz_util_now (gfa_now / parcel_area) of the cohort, percentile_cont(0.5). Null when n_cz_util_now is 0.
  
  p80_cz_util_now
  optional
  number | null
  80th percentile of cz_util_now of the cohort, percentile_cont(0.8). Null when n_cz_util_now is 0.
  
  n_cz_util_now
  optional
  integer
  Parcels in the cohort with a usable cz_util_now (the sample behind the mean and the two percentiles).
  
  mean_cz_util_now
  optional
  number | null
  Mean cz_util_now (gfa_now / parcel_area) of the cohort, over the same rows as the percentiles (weight: n_cz_util_now). Null when n_cz_util_now is 0.
- last5
  optional
  object
  One age cohort of the zone, on utilization: the mean, p50 and p80 of cz_util_now (gfa_now / parcel_area, the floor-area utilization) over the same parcels, with n_cz_util_now as their sample size. mean_cz_util_now was added in v0.0.323. The deprecated mean_ratio_v (not utilization) was removed in v0.0.324.
  
  cohort_label
  string
  required
  n
  integer
  required
  p50_cz_util_now
  optional
  number | null
  Median cz_util_now (gfa_now / parcel_area) of the cohort, percentile_cont(0.5). Null when n_cz_util_now is 0.
  
  p80_cz_util_now
  optional
  number | null
  80th percentile of cz_util_now of the cohort, percentile_cont(0.8). Null when n_cz_util_now is 0.
  
  n_cz_util_now
  optional
  integer
  Parcels in the cohort with a usable cz_util_now (the sample behind the mean and the two percentiles).
  
  mean_cz_util_now
  optional
  number | null
  Mean cz_util_now (gfa_now / parcel_area) of the cohort, over the same rows as the percentiles (weight: n_cz_util_now). Null when n_cz_util_now is 0.
}
parcels
array of
object
required
Unfiltered per-parcel scatter input - egrid, parcel area, built volume, latest construction year.
- egrid
  optional
  string
- area
  optional
  number | null
- volume
  optional
  number | null
- year
  optional
  integer | null
}
_lang
optional
string | null

304

If-None-Match matches the current ETag. Empty body; answered before the payload is computed.

400

Missing or invalid fso / cz_local.

JSON

error
string
required
Human-readable error description.
message
optional
string
Optional underlying error message.

401

Missing token.

JSON

error
string
required
Human-readable error description.
message
optional
string
Optional underlying error message.

403

Wrong token.

JSON

error
string
required
Human-readable error description.
message
optional
string
Optional underlying error message.

409

snapshot was given and is not the current snapshot. Cache-Control: no-store.

JSON

error
optional
string
snapshot
optional
string
The current snapshot.

500

Server error.

JSON

error
string
required
Human-readable error description.
message
optional
string
Optional underlying error message.