Skip to content
Aireon Developers
Navigation

Comparable buildings for the similoo 3D viewer

Given a target parcel EGRID, returns the parcel's own metrics plus a ranked list of comparable parcels in the same zoning (cz_local) with recent construction. The primary candidate pool joins gwr_new_projects (the monthly scraper feed) onto parcel_2025_07 via a 50 m centroid radius; when fewer than 5 comparables match, the endpoint falls back to parcel_2025_07's own bldg_vol_sb3dgdb / cy_max columns (meta.fallback_used = 'parcel_table'). Similarity is computed in normalised z-space over (parcel_area_m2, building_volume_m3, ratioV) and inverted to 1 / (1 + distance). Response is cached in Redis for 7 days under similoo:v4:egrid:<EGRID>:years:<years|all>:limit:<limit>. The version segment moves with the payload shape: v3 added the same-municipality gate, v4 the unrestricted window, and the window segment renders as all rather than null so a numeric-window payload can never be served for an unrestricted request.

POST
https://res.aireon.ch/score/similoo

Authorization

  • ResApiToken
    API key in header
    required

Request body JSON required

  • egrid
    string
    required

    Swiss EGRID (CH + 12 alphanumerics).

  • years
    optional

    Construction-year window. Any integer 1-100; the suite precision ladder uses the steps 5 / 10 / 15 / 20 / 40 / 60. Pass the string "all" (case-insensitive) or the number 0 for an unrestricted window with no construction-year floor at all. NOTE 100 is not "all" - Swiss parcels carry construction years well before 1926. A missing or unparseable value falls back to 10, never to unrestricted.

    default: 10

    One of the following:

    • integer
    • string
  • limit
    optional
    integer

    Max comparables to return. Default 20.

    maximum: 200 · minimum: 1 · default: 20

Returns

200

Target parcel metrics + ranked comparables.

JSON
  • target
    optional
    object
    • egrid
      optional
      string
    • municipality
      optional
      string | null
    • cz_local
      optional
      string | null
    • cz_abbrev
      optional
      string | null
    • parcel_area_m2
      optional
      number | null
    • building_volume_m3
      optional
      number | null
    • height_m
      optional
      number | null
    • floors
      optional
      integer | null
    • construction_year
      optional
      integer | null
    • ratioV
      optional
      number | null
    • lat
      optional
      number | null
    • lng
      optional
      number | null
  • comparables
    optional
    array of
    object
    • egrid
      optional
      string
    • municipality
      optional
      string | null
    • cz_local
      optional
      string | null
    • parcel_area_m2
      optional
      number | null
    • building_volume_m3
      optional
      number | null
    • footprint_m2
      optional
      number | null
    • height_m
      optional
      number | null
    • floors
      optional
      integer | null
    • construction_year
      optional
      integer | null
    • ratioV
      optional
      number | null
    • similarity_score
      optional
      number
    • lat
      optional
      number | null
    • lng
      optional
      number | null
  • meta
    optional
    object
    • gwr_month
      optional
      string | null
    • total_candidates
      optional
      integer
    • years_window
      optional
      integer | null

      The applied window in years, or null when unrestricted. Read years_window_all rather than treating null as "unknown".

    • years_window_all
      optional
      boolean

      True when the window was unrestricted (years "all" or 0).

    • fallback_used
      optional
      null
      or
      parcel_table

      null when the GWR-based pool was used, "parcel_table" when the parcel-table fallback produced the list.

    • generated_at
      optional
      string
      format: date-time

400

Invalid request.
JSON
  • error
    string
    required

    Human-readable error description.

  • message
    optional
    string

    Optional underlying error message.

401

Authentication token missing (plain-text body).

403

Authentication token invalid (plain-text body).

404

No parcel found for the supplied EGRID, or the target parcel has no cz_local zoning.
JSON
  • error
    optional
    string

500

Server error.
JSON
  • error
    string
    required

    Human-readable error description.

  • message
    optional
    string

    Optional underlying error message.

Type to search…

↑↓ navigate↵ selectEsc close