Building volume statistics inside an arbitrary drawn polygon

The polygon counterpart of /res_api/bldg_vol_bbox: instead of a circular buffer it evaluates the ACTUAL polygon in PostGIS, so the count matches exactly what the user drew. A building belongs to the polygon when its footprint CENTROID (building_footprint_rf.geom) is inside - no double counting across neighbouring polygons, no boundary bleed. Volumes are rf_volume_lod22 (roofer LoD2.2).

The outer ring is closed automatically, must have ≥ 3 distinct vertices and ≤ 10,000, and its geodesic area is gated to 2,500..250,000 m² (mirroring the footprint client's drawing limits) by a cheap area-only query BEFORE the footprint count runs. The response mirrors /bldg_vol_bbox field-for-field so density clients render it unchanged; density.bbox_area_m2 is the polygon's own area.

Auth quirk inherited from /bldg_vol_bbox: a MISSING token header is a 400, a WRONG one is a 401 (not 401/403). Real status codes, JSON bodies, no X-RES-API-Version needed. Not cached.

POST

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

Authorization

ResApiToken
API key in header
required

Request body JSON required

polygon
optional
object
- type
  string
  required
- coordinates
  array of
  array<array<number>>
  required
  GeoJSON rings, WGS84 [lng, lat].
}
ring
optional
array of
array<number>
Outer ring as [[lng, lat], …]. Closed automatically if the last vertex differs from the first.
coordinates
optional
array of
array<number>
Alias of ring.

Example requests

{
  "polygon": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          8.54,
          47.376
        ],
        [
          8.545,
          47.376
        ],
        [
          8.545,
          47.379
        ],
        [
          8.54,
          47.379
        ],
        [
          8.54,
          47.376
        ]
      ]
    ]
  }
}

Returns

200

Building volume statistics for the polygon.

JSON

success
optional
boolean
input
optional
object
- vertex_count
  optional
  integer
  Distinct vertices of the closed ring.
- polygon_area_m2
  optional
  number
  Geodesic area of the polygon.
}
statistics
optional
object
- total_building_count
  optional
  integer
- buildings_with_volume
  optional
  integer
- buildings_without_volume
  optional
  integer
- total_volume_m3
  optional
  number
- avg_volume_m3
  optional
  number | null
- min_volume_m3
  optional
  number | null
- max_volume_m3
  optional
  number | null
- total_footprint_area_m2
  optional
  number
}
density
optional
object
- bbox_area_m2
  optional
  number
  Named for compatibility with /res_api/bldg_vol_bbox; here it is the polygon's own area (m²).
- volume_density_bbox_m3_per_m2
  optional
  number
  total_volume_m3 / polygon area, 4 dp.
- volume_density_footprint_m3_per_m2
  optional
  number
  total_volume_m3 / total footprint area, 4 dp.
}

400

Missing token (Missing Token), no polygon/ring/coordinates, fewer than 3 vertices, non-numeric vertices, more than 10,000 vertices, or an area outside 2,500..250,000 m² (the message carries the measured area).

JSON

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

401

Wrong token.

JSON

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

500

PostGIS error - {"error":"Server error","message":"…"}.

JSON

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

curl --request POST \ --url https://res.aireon.ch/res_api/bldg_vol_polygon \ --header 'Content-Type: application/json' \ --header 'token: <token>' \ --data ' { "polygon": { "type": "Polygon", "coordinates": [ [ [ 8.54, 47.376 ], [ 8.545, 47.376 ], [ 8.545, 47.379 ], [ 8.54, 47.379 ], [ 8.54, 47.376 ] ] ] } } '

{ "success": true, "input": { "vertex_count": 4, "polygon_area_m2": 125874.3 }, "statistics": { "total_building_count": 87, "buildings_with_volume": 85, "buildings_without_volume": 2, "total_volume_m3": 412350.5, "avg_volume_m3": 4851.2, "min_volume_m3": 120.4, "max_volume_m3": 38210.9, "total_footprint_area_m2": 31240.7 }, "density": { "bbox_area_m2": 125874.3, "volume_density_bbox_m3_per_m2": 3.2759, "volume_density_footprint_m3_per_m2": 13.1991 } }