Boundary layer height vs soaring height: they are not the same
`boundary_layer_m` and `hglider_agl_m` are two different numbers in the API. They come from the same meteorology but mean different things, and mixing them up gives you the wrong briefing.
The API returns two vertical extent fields that sound similar. `boundary_layer_m` is the depth of the atmospheric boundary layer, in metres. `hglider_agl_m` is the useable thermalling ceiling, also in metres AGL. On some days they are within 50 m of each other. On other days they are 1000 m apart. If you are building a pilot-facing display, you need to know which to show and why.
`boundary_layer_m` is a physical quantity that comes directly from the PBL scheme. It is the height at which the model decides the turbulent mixing from the surface has run out and the free atmosphere begins. Definitions vary slightly between schemes (YSU uses a bulk Richardson number, MYNN uses a TKE threshold), but the concept is the same: the top of the layer where surface-driven turbulence dominates.
`hglider_agl_m` is an engineered quantity designed to be the altitude a pilot actually reaches on a given day. It takes `boundary_layer_m` as an input, then caps it by cloudbase (you cannot go into cloud legally), subtracts a safety margin, and accounts for the fact that the top 10 to 15 percent of the boundary layer is usually weak enough that climbs top out below the formal PBL top.
When they agree. On blue days (no cumulus, so no cloudbase cap) with a sharp capping inversion, the two numbers are usually within 100 m of each other. The boundary layer tops out cleanly, the top of useable lift is near the PBL top, and the only correction `hglider_agl_m` makes is the top-of-layer weakening.
When they diverge. On humid days with low cloudbase, `hglider_agl_m` gets capped by cloudbase while `boundary_layer_m` continues growing above. You can see 1100 m for `hglider_agl_m` and 2000 m for `boundary_layer_m` on the same query. The pilot's working ceiling is 1100 m. The atmospheric convective layer extends to 2000 m. Both are correct.
On days with tall shallow convection capped by a weak inversion, the opposite happens: cloudbase sits above the PBL top (because the PBL is dry), and `hglider_agl_m` is limited by the boundary layer while the atmosphere above has cumulus forming on imported moisture at a higher level. Rare but real.
Which to show pilots. Show `hglider_agl_m`. It is the altitude that answers their question (how high can I climb). `boundary_layer_m` is more useful for meteorologists and integrators doing their own derivations, and for diagnosing when the model is behaving unusually.
Which to show meteorological integrators. Both. The ratio between them is diagnostic. `hglider_agl_m` very close to `boundary_layer_m` means the cap is atmospheric stability, which is typically a reliable forecast. `hglider_agl_m` much lower than `boundary_layer_m` means the cap is moisture, which is where cloudbase errors bite hardest. A display that shows the ratio or the difference can help a user calibrate how much to trust the ceiling.
Both fields are in every site response. The API reference has the full schema. Next field explainer is about reading a forecast sounding, which is where all of these numbers come from originally.