AAPI reference · base https://daylighting.kairoico.com/v1/aec
Plain HTTPS. GET for quick calls, POST for geometry uploads. Every response is one JSON object with the inputs echoed, the standard's citation, and the verdict where a threshold exists. Nothing you upload is stored: meshes are analysed in memory and deleted before the response leaves.
# The two-minute check: a neighbour's window, a proposed wall curl "https://daylighting.kairoico.com/v1/aec/vsc?window_az_deg=180&wall_az_lo=135&wall_az_hi=225&wall_dist_m=10&wall_height_m=10" {"vsc_percent": 18.8785, "sky":"overcast", "convention":"BRE unobstructed denominator", ...}
BConventions
Frame: metres; y up, −z south, x east (rotate a survey-north model with north=<deg>). Boxes are opaque axis-aligned blocks [x0,y0,z0,x1,y1,z1]; light enters through gaps — model a window as four wall boxes framing the opening. Meshes: OBJ, glTF/GLB or IFC up to 64 MiB, sent multipart on POST. Grids: x0 z0 x1 z1 plane_y nx nz, up to 4,096 points, returned point-by-point for heatmaps. Unknown parameters are rejected with a 400 — nothing is silently ignored.
CVerbs
Vertical sky component with analytic obstructions (wall bands) and an external-reflectance term. BRE 209 §2.2 — validated to ≤0.13 pp vs Radiance.
| window_az_deg | window outward azimuth, 0=N compass |
| window_tilt_deg | 90 vertical (default) · 0 rooflight |
| wall_az_lo · wall_az_hi · wall_dist_m · wall_height_m | optional obstructing wall band |
| ext_reflectance | 0–1, reflected-light allowance |
VSC by true ray-casting against your uploaded mesh and/or boxes — the neighbour's window against the actual proposal. Validated to ≤0.09 pp vs Radiance on identical triangles.
| window_az_deg · window_tilt_deg | as above |
| obs_x · obs_y · obs_z | window reference point |
| file · mesh_ref | multipart mesh upload, or a named server asset |
| boxes | JSON list of opaque blocks |
| zup=1 · north=<deg> | axis fix-ups for CAD exports |
Sky-component DF at a point, and the Lynes average-DF method (τ·Aw·θ·M / A·(1−R²)) with the standard worked example reproduced exactly.
Per-point DF over the working plane: mean, median, % ≥ target, and the full grid for heatmaps. Validated: per-point vs Radiance max 0.14 pp.
| grid ×7 | x0 z0 x1 z1 plane_y nx nz |
| tau_vlt | glazing visible transmittance |
| target | DF % to score against — a generic default of 2.0, not a BRE 209 requirement. Room-specific targets (1 / 1.5 / 2 % for bedroom / living / kitchen) come from the legacy BS 8206-2; pass your own via target=. |
No-sky-line map: which working-plane points can see any sky at all. Returns the 0/1 grid and the area percentage. Validated 36/36 against Radiance per-point visibility.
Annual and winter probable sunlight hours at a window from EPW climate data. Definitions in the response: sunny = DNI ≥ 120 W/m² (WMO); winter = 21 Sep–21 Mar; sufficiency thresholds 25 % / 5 %. Pass the former (existing-scene) values to also get the BRE 209 §3.2 development-impact loss verdict.
| px · py · pz · window_az_deg | window centre and facing |
| epw_file | named EPW climate file (upload coming) |
| former_annual_percent · former_winter_percent | the window's APSH from a prior "before" run — supply both to return loss_verdict (noticeable-loss / within-guidance) via the four-part §3.2 test: below the 25 % / 5 % guideline, below 0.8× former in either period, and > 4 % annual reduction |
The garden test: percentage of an amenity area receiving ≥ 2 hours of sun on 21 March, with the ≥ 50 % verdict and the per-point map. 6-minute sun steps.
Transient overshadowing: sun/shade bitmap of the site at each requested local time — the frames behind every shadow-study figure.
| month · day · hours | e.g. month=3&day=21&hours=9,12,15 |
| lat · lon · tz | site position |
Annual sDA / ASE / mean DF on a grid with EPW weather, four sky models and a reflectance term. Cross-checked against a Radiance two-phase run on the reference room — exact aggregate and per-point agreement at R = 0 (Sheet 02 §F).
DGP glare class per Wienold & Christoffersen 2006 with EN 17037 boundaries, and SGHAT specular-reflection ocular safety per Ho et al. — both formula-exact against the papers.
Upload OBJ / glTF / IFC (≤ 64 MiB): triangle count, bounds, axis report. Store-nothing: the file lives in memory for the duration of the call and is deleted before the response returns.
DKeys & limits
Access is set up one to one. For an evaluation key — or to have us run your geometry as a smoke test — write to hello@kairoico.com with your practice and the geometry format you work in. Grid verbs are sized to stay inside a 120 s response; larger annual jobs run through an async job API.