Cloud base altitude is one of those fields that every aviation and outdoor-operations app wants and almost no general weather API actually provides cleanly. WeatherAPI doesn’t surface a cloud_base_m field in the standard forecast or current-conditions response. If you’ve gone looking for it, you’ve already noticed that.
What the API does give you is enough to derive a defensible estimate — not a certified ceiling reading, but something genuinely useful that beats ignoring the question entirely. Here’s the derivation and where it breaks down.
Why Cloud Base Isn’t a Single Field
Ceiling altitude is hard to expose via API because it’s not a single measured quantity — it’s a diagnosis. METAR reports include ceiling height when observed below 10,000 feet AGL, but that’s a human-readable encoding of sky condition groups (FEW/SCT/BKN/OVC) with associated heights, not a raw sensor reading. Automated surface observation systems (ASOS) measure it with ceilometers, but that measurement is specific to the station location and only appears in METARs, not in gridded model output.
Numerical weather models — GFS, NAM, HRRR — carry cloud fraction at multiple pressure levels. HRRR’s 3km horizontal resolution is good enough to represent convective cloud structure, but the vertical level output still needs translating into an AGL height. That translation requires knowing the terrain height under the grid cell, then scanning upward through pressure levels to find where cloud fraction exceeds a reporting threshold. It’s doable in a GRIB2 pipeline, and we do ingest HRRR and GFS model output — but surfacing that as a clean field for every location on every request isn’t something we’ve exposed yet. The derivation below is how you can build a reasonable proxy from what’s already in the response.
The Surface Dew Point Method
The simplest physically-grounded estimate uses the spread between surface temperature and dew point. The rule comes from the standard dry adiabatic lapse rate and the dew point lapse rate: temperature drops roughly 9.8°C per 1,000m as you rise through dry air, while dew point drops only about 1.8°C per 1,000m. The two converge at the lifted condensation level (LCL) — roughly where cumulus cloud bases form in convective conditions.
The arithmetic simplifies to:
cloud_base_m ≈ (temp_c - dewpoint_c) / 0.008That denominator, 0.008°C/m, is just the difference in lapse rates (9.8 – 1.8 = 8.0°C per 1,000m). WeatherAPI gives you temp_c and dewpoint_c directly in the current conditions and hourly forecast responses, so you can compute this in two lines anywhere you’re already parsing the response.
Concrete example: a response showing temp_c: 14.0 and dewpoint_c: 7.5 gives a spread of 6.5°C. Divide by 0.008 and you get a cloud base estimate around 812 meters AGL — roughly 2,700 feet, consistent with scattered cumulus in cool maritime air.
When This Method Is Worth Using and When It Isn’t
The LCL approach works reasonably well for convective cloud — cumulus and cumulonimbus, the stuff that forms when surface air rises and cools to its dew point. NWS forecasters use it for quick back-of-envelope cloud base estimates in unstable air.
It falls apart in a few specific situations common enough to flag explicitly:
- Stratiform cloud and fog: When cloud is advected in rather than convected up — stratus, fog lifting off the surface, low overcast from a frontal system — the LCL method gives you garbage. The cloud base can be at 100 meters while the spread gives you 600. In these cases,
vis_kmcollapsing is a better first indicator than spread alone. - Elevated terrain: The derivation gives AGL height relative to the surface. If your location is already at 800m elevation, adding a cloud base of 800m to get MSL altitude matters for aviation. WeatherAPI returns
elevation_min the location block — use it. Without it, you’ll underestimate MSL ceiling for mountainous requests. - Temperature inversions: An inversion traps moisture below it and can support a low cloud layer even when the surface spread looks wide. If
pressure_mbhas been rising steadily — a rough inversion indicator in stable post-frontal air — andcloudis still high, don’t trust the spread method to find that ceiling.
Using Cloud Cover to Gate the Estimate
The LCL estimate is only meaningful when cloud is actually present. WeatherAPI returns cloud as a percentage (0–100) in both current and forecast responses. If cloud < 25, you’re looking at FEW coverage or clear — no ceiling to report. Between 25 and 50, you have scattered coverage. At 50%+ you’re approaching broken or overcast, where a ceiling exists in the aviation sense.
Combining the two gives you something more defensible:
spread = temp_c - dewpoint_c
if cloud >= 50 and spread is not null:
ceiling_m_agl = spread / 0.008
ceiling_msl = ceiling_m_agl + elevation_m
else:
ceiling = None # don't fabricate a numberThat’s not an aviation-certified ceiling. ICAO regulations require an actual ceilometer reading or METAR-reported ceiling for instrument approach decisions. But for a hiking app, construction scheduling tool, or low-ceiling early-warning display, this is genuinely useful — and it’s honest about what it’s doing rather than surfacing a fake-precise number.
What METAR Can Add (And Why It’s Still Incomplete)
If ceiling accuracy matters a lot for your use case — drone operations, pipeline patrols, anything where actual VFR/IFR determination is on the line — supplement the derived estimate with a real METAR from a nearby station. METARs from ICAO stations include sky condition groups with reported heights in hundreds of feet, and the lowest BKN or OVC layer is the ceiling by definition.
The limitation is station density. Outside North America and Western Europe, METAR coverage gets thin quickly. And even where it’s dense, the nearest station can be 20–30km away with significant terrain between it and your location. A ceilometer reading at a valley station doesn’t describe the ceiling over a ridge 15km away — cloud base can differ by hundreds of meters.
We handle that representativeness problem in our METAR station selection with composite scoring that weights elevation difference alongside distance, but even then, a single station reading is a point observation, not a spatial field. The derived estimate from local temp and dew point at least reflects local surface conditions rather than conditions at a distant station.
The Practical Implementation Path
All the fields you need are already in the same response you’re fetching:
current.temp_corforecast.forecastday[n].hour[h].temp_ccurrent.dewpoint_cor the hourly equivalentcurrent.cloud(0–100)location.elevation_mfor MSL conversion
No extra endpoint. No additional quota cost. The derivation adds maybe five lines of logic to whatever you’re already doing with the response.
One practical note: dewpoint_c wasn’t always in the response — it was added to current conditions and the hourly forecast relatively recently. If you’re on an older integration or caching the response schema rather than parsing it defensively, check that the field is actually present before computing the spread. A null dew point will silently produce a nonsense ceiling if you’re not guarding against it.
To sanity-check the estimate against something observable, compare your computed ceiling against vis_km: in low-ceiling conditions, visibility and ceiling tend to degrade together. A computed ceiling of 200m alongside vis_km of 2.0 is internally consistent. A 200m ceiling alongside vis_km of 15.0 should raise a flag — you’re likely in the inversion or advection scenario where the spread method has lost contact with reality.
Before wiring up a continuous ceiling estimate, ask whether your app actually needs it as a number at all. For most non-aviation use cases, a threshold flag — “ceiling below 300m: yes/no” — is what drives the decision anyway, and a threshold is far easier to validate against METAR ground truth than a continuous estimate is. Start there.