Skip to content
Aireon Developers
Navigation

Start a 3D building extract around an address or a WGS84 point

Backs the aireon hub '3D extract' admin page and the Grasshopper/API path. Geocodes the address (geo.admin SearchServer) - or, when lat+lng are given, takes that WGS84 point directly (LV95 via the swisstopo REFRAME service; label and EGID from the GWR building under the point, best effort) - finds the newest per-sheet swisstopo swissBUILDINGS3D 3.0 Beta tile via the data.geo.admin.ch STAC API (FileGDB, cached under cache/building3d/), clips all buildings intersecting the ±radius_m box around the point (whole buildings, not sliced; layers Building_solid + Roof_solid), builds an OBJ/MTL mesh (local origin at the point, Y-up) + a georeferenced DXF (3DFACE mesh on WALL/ROOF layers, absolute LV95/LN02 metres - opens in AutoCAD/BricsCAD/Rhino/SketchUp) + a DWG R2000 (same mesh, converted from the DXF via LibreDWG when available) + GeoPackage (EPSG:2056, full attributes incl. EGID and heights) + preview render + README, and zips it as <slug>_3d_<radius>m.zip.

Responds 202 immediately with a jobId. Two ways to get the result: (1) give an email and the zip (or a failure report - unknown address, no tile covering the point, empty box) arrives by Resend in about a minute, exactly as before; (2) poll statusUrl until status is ready, then GET downloadUrl (the zip) or downloadUrl/{file} for one member. Without email no mail is sent at all. Outputs are kept under cache/building3d/jobs/<jobId>/ and evicted least-recently-used once the jobs directory exceeds its cap (default 5 GiB, BUILDING3D_JOBS_MAX_BYTES); the download endpoints touch a job on every fetch, so a result that keeps being fetched stays.

Concurrency: at most 3 extractions per pm2 worker (RES runs 2 cluster workers, so 6 box-wide); beyond that the request is answered 429 and should simply be retried a minute later.

POST
https://res.aireon.ch/res_api/building3d-extract

Authorization

  • ResApiToken
    API key in header
    required

Request body JSON required

Any of the following:

  • Option 1
  • Option 2

Example requests

{
  "address": "Rainweg 1 4710 Balsthal",
  "radius_m": 10,
  "email": "someone@example.com"
}

Returns

202

Job accepted and the worker spawned. Legacy fields (ok, address, radius_m, email, note) are unchanged for the hub form; the job fields tell an API client where to poll and download.

JSON
  • ok
    boolean
    required

    Always true on 202 (legacy hub field).

  • address
    string | null
    required

    The address as received, or null for a point request.

  • radius_m
    number
    required

    The clamped radius actually used.

  • email
    string | null
    required

    Recipient of the result e-mail, or null when none will be sent.

  • note
    string
    required

    Human-readable hint on how the result will arrive.

  • jobId
    string
    required
    format: uuid
  • status
    queued
    required
  • statusUrl
    string
    required

    /res_api/building3d-extract/status/{jobId} - poll until ready.

  • downloadUrl
    string
    required

    /res_api/building3d-extract/download/{jobId} - the zip once ready; append /{file} for one member.

  • lat
    optional
    number | null
  • lng
    optional
    number | null

400

Neither a usable address (4–200 chars) nor a lat+lng pair inside Switzerland, or an invalid email.
JSON
  • error
    string
    required

    Human-readable error description.

  • message
    optional
    string

    Optional underlying error message.

401

Authentication missing or invalid.
JSON
  • error
    string
    required

    Human-readable error description.

  • message
    optional
    string

    Optional underlying error message.

403

Authenticated but not permitted.
JSON
  • error
    string
    required

    Human-readable error description.

  • message
    optional
    string

    Optional underlying error message.

429

All extraction slots busy (3 per pm2 worker, 6 box-wide). Retry in a minute.
JSON
  • error
    string
    required

    Human-readable error description.

  • message
    optional
    string

    Optional underlying error message.

500

The job directory could not be created or the worker could not be started.
JSON
  • error
    string
    required

    Human-readable error description.

  • message
    optional
    string

    Optional underlying error message.

Type to search…

↑↓ navigate↵ selectEsc close