RES API (public)
Canonical OpenAPI 3.1 contract for the RES (Real Estate Scoring) API that powers the Aireon suite of apps.
This document describes the API exactly as it behaves today - it is documentation, not a redesign. No endpoint, parameter, response shape, or auth rule was changed by introducing this file, so every existing client keeps working unchanged.
Error contract - opt in to corrected status codes
The legacy parcel and OEREB endpoints historically returned authentication and validation errors as HTTP 200 with a plain-text body (for example Missing Token, Wrong Token, coordinate missing). To correct this without breaking existing callers, the fixed behaviour is opt-in via a request header:
- Send
X-RES-API-Version: 2to receive a proper4xx/5xxstatus code with a JSON{ "error": ... }body. - Omit the header to get the unchanged legacy behaviour (HTTP 200 + plain text).
New integrations should always send X-RES-API-Version: 2. Once every caller is migrated the default will be flipped. The /score/*, /res_api/signal/*, /res_api/building_data, /res_api/bldg_vol_bbox, and /image/aireon/* endpoints already use proper status codes regardless of the header. Note: GET /res_api/parcel_image is used directly in <img> tags, which cannot send the header - its auth and validation errors therefore always use legacy behaviour, while its server and upstream failures always answer a real 500 / 502.
Scope
This is the public subset of the RES API: parcel search and data, zone statistics, building data and 3D, POI scoring and routing, GWR building records, OEREB documents, valuation and the PRM listing monitor.
Each operation carries x-aireon-pack, the data pack an API key needs for it (core is free).
Every operation needs a token unless its security is empty. Developer guide: https://docs.aireon.ch
Parcel
Parcel data, geometry, imagery and building information.
- Site facts (woom digital values) for one parcelGET
/res_api/dd/metric/{egrid} - Get parcel data by coordinate or EGRIDGET
/res_api/parcel_data - Get parcel data by coordinate or EGRIDPOST
/res_api/parcel_data - Distributions and summary statistics for a zoning category in a communeGET
/res_api/zone_stats - Distributions and summary statistics for a zoning category in a communePOST
/res_api/zone_stats - Exact address point plus every address on its parcelGET
/res_api/address_geocode - Get a parcel and its neighbouring parcelsGET
/res_api/parcel_data_neighbor - Get a parcel and its neighbouring parcelsPOST
/res_api/parcel_data_neighbor - Render a parcel image (PNG) - query-string variantGET
/res_api/parcel_image - Render a parcel image (PNG) - JSON body variantPOST
/res_api/parcel_image - Request a 3D building model (async, delivered by email)POST
/res_api/buildingModel - Request contour (Contoor) data (async, delivered by email)POST
/res_api/contour_data - Get building height and volume at a locationPOST
/res_api/building_data - Building volume statistics within a bounding boxPOST
/res_api/bldg_vol_bbox - Current air quality at a locationGET
/res_api/airquality - Get OEREBlex documents for a municipality (FSO number)GET
/res_api/fso-docs/{fsoNum} - Water-scenario data for a parcelPOST
/res_api/fb_water - Structured parcel search with a fast LIMIT fetch and a capped countPOST
/res_api/parcel_search - Distinct localities, municipalities and locality→municipality aliases for autocompleteGET
/res_api/parcel_search/locations - Spare-space candidates inside a bounding box (GeoJSON)GET
/res_api/spare_space - Active spare-space snapshot name and candidate countGET
/res_api/spare_space_meta - Building volume statistics inside an arbitrary drawn polygonPOST
/res_api/bldg_vol_polygon
Building3D
swissBUILDINGS3D 3.0 Beta clip-and-email extracts (aireon hub '3D extract' page). Worker: scripts/building3d/extract_building3d.py.
- Start a 3D building extract around an address or a WGS84 pointPOST
/res_api/building3d-extract - Building footprints with heights and volumes (GeoJSON, sync)GET
/res_api/building_footprints - Building footprints with heights and volumes (GeoJSON, sync) - JSON body variantPOST
/res_api/building_footprints - Single-building 3D model (OBJ / GLB / CityJSON / DXF), synchronousPOST
/res_api/3d/building_model - Download one artifact of a building model through RESGET
/res_api/3d/building_model/file/{buildingId}/{file} - Merged 3D model of every building in a square around a point (async job, emailed)POST
/res_api/3d/building_model/area - Poll an asynchronous 3D jobGET
/res_api/3d/jobs/{jobId} - Clipped swissSURFACE3D point cloud as GeoJSON pointsPOST
/res_api/3d/pointcloud - Contour lines from swissSURFACE3D around a point (GeoJSON / DXF / Shapefile), streamedGET
/res_api/3d/contour - Poll a 3D extract jobGET
/res_api/building3d-extract/status/{jobId} - Download the zip of a finished 3D extractGET
/res_api/building3d-extract/download/{jobId} - Download one member of a finished 3D extractGET
/res_api/building3d-extract/download/{jobId}/{file}
Score
Points-of-interest scoring around a location.
- Count of points of interest around a locationGET
/score/poi-num - Detailed points of interest around a locationGET
/score/poi-details - Detailed points of interest within a travel-time isochroneGET
/score/poi-details-driving-distance - Walkability POIs around a location (local OSM dataset)GET
/score/poi-osm - Comparable buildings for the similoo 3D viewerPOST
/score/similoo - Walking distance/duration from one origin to many destinations (query variant)GET
/res_api/routing/table - Walking distance/duration from one origin to many destinations (JSON body variant)POST
/res_api/routing/table
OEREB
Official cadastral public-law restriction (OEREB) extract links.
Meta
Health and service metadata.
GWR
New-building-projects feed from the GWR register, served from Postgres with a Redis cache. Loaded monthly by gwr/load_new_projects.js.
- List loaded monthly runsGET
/res_api/gwr/months - One run's metadata and summaryGET
/res_api/gwr/summary - List buildings (filtered, paginated)GET
/res_api/gwr/projects - One building by EGIDGET
/res_api/gwr/projects/{egid} - Buildings as a GeoJSON FeatureCollectionGET
/res_api/gwr/geojson - Dwelling (Wohnung) records for one or more buildings, by EGID or by parcel EGRIDGET
/res_api/gwr/dwellings
PRMMonitor
PRM listing monitor: attach real-estate ad URLs to parcels in the caller's PRM pipeline, list them, stop monitoring. Report-driven: the server never fetches a listing page. Registering a URL again is an observation (status, price, content hash) that can emit listing events. Errors use `{ "error": { "code", "message" } }` and every response carries `Cache-Control: private, no-store`. A malformed JSON body answers 400 `invalid_request` and a body over the size cap 413 `payload_too_large`, both before authentication. After authentication, an unknown path under `/res_api/prm_monitor` answers 404 `not_found`.
- Monitor a real-estate ad on a parcel, or track a parcel without an ad link (listing fields are untrusted text)POST
/res_api/prm_monitor/listings - Monitor up to 25 ads or track up to 25 parcels in one call (omit url to track a parcel without an ad link; listing fields are untrusted text)POST
/res_api/prm_monitor/listings/batch - List the caller's monitored parcels and their ad links (listing fields are untrusted text)GET
/res_api/prm_monitor/records - One monitored parcel with all its ad links and recent events (listing fields are untrusted text)GET
/res_api/prm_monitor/records/{id} - List the parcels on the user's proom board: label, EGRID, stage, last activity and whether each is monitored (labels are untrusted text)GET
/res_api/prm_monitor/parcels - Stop monitoring one ad link, or all links of a parcel (listing fields are untrusted text)POST
/res_api/prm_monitor/stop
Valuation
Parcel valuation computed by revenoo (RICS methods) and served through the RES API: the land value by initial yield on cost. Responses are revenoo's, cached 6 h in Redis.