solar_rad sits in WeatherAPI responses as a single float in W/m², quiet and easy to overlook. Most developers either skip it entirely or treat it as a direct readout of sunshine intensity. Neither works, and the bugs that follow are annoying to diagnose because the numbers look fine until they’re suddenly very wrong.
Here’s what the field actually measures and what you can usefully do with it.
What solar_rad Is Measuring
solar_rad is global horizontal irradiance (GHI) — total solar radiation hitting a flat, horizontal surface at ground level. It combines direct beam radiation from the sun’s disc, diffuse radiation scattered by the atmosphere, and terrain-reflected radiation. What it does not give you is direct normal irradiance (DNI), which is what concentrating solar collectors need, or plane-of-array irradiance, which is what a rooftop PV system actually sees once panel tilt and azimuth enter the picture.
That distinction matters the moment you’re doing any solar energy estimation. GHI is a reasonable starting point for flat-panel calculations, but you need to run it through a decomposition model — Erbs, Dirint, or Perez are the standard choices — to split it into DNI and diffuse horizontal irradiance (DHI) before applying a transposition model for a tilted surface. Feeding solar_rad directly into a panel output estimate gives you numbers that are wrong in a direction that depends on time of day, season, and cloud cover all at once, which makes them hard to sanity-check by eye.
Where the Value Comes From
For current and recent observations, solar_rad comes from station pyranometers where available. Coverage is patchier than temperature or pressure — not every station has one, and the ones that do aren’t always nearest to the coordinate you’re querying. For forecast periods, the value is derived from NWP model output. GFS and ECMWF both include downwelling shortwave radiation in their output grids; our GRIB2 ingestion pipeline pulls this alongside the standard meteorological variables.
Model resolution matters more for solar than it does for temperature. GFS runs on roughly a 13 km grid. NOAA’s HRRR runs at 3 km with rapid refresh cycles, and that difference shows up in convective cloud situations — cloud optical depth can change fast during active convection, and a coarser grid smears that across space in a way that degrades irradiance accuracy. On a 15-minute to 1-hour horizon with developing cumulus, HRRR-derived values are noticeably better. At 7-day range, it stops mattering because both models are equally uncertain about cloud placement that far out.
The Cloud Transmissivity Problem
Cloud cover is the dominant control on GHI, and it’s where solar_rad gets genuinely tricky. The relationship between cloud cover percentage and surface irradiance is non-linear and depends heavily on cloud type. A 60% cover of thin cirrus transmits far more radiation than 60% cover of cumulonimbus. Stratocumulus — the shallow overcast that dominates UK and Pacific coast summers — sits somewhere in between but varies significantly with liquid water path.
The cloud field is a percentage, and the tempting move is to multiply solar_rad by (1 - cloud/100) as a quick correction. Don’t. The model has already applied a cloud transmissivity estimate when producing solar_rad. Multiplying again double-counts cloud attenuation and produces values that are systematically too low on overcast days. The right sanity check is to compare solar_rad against the theoretical clear-sky value for that latitude, date, and solar elevation angle. If the ratio is near 1.0 and reported cloud cover is 90%, something is off in one of the two fields — not both.
One edge case worth knowing: solar_rad can legitimately exceed clear-sky GHI. Broken cumulus fields produce cloud-enhancement effects where direct beam and forward-scattered light from cloud edges briefly push ground-level irradiance above the clear-sky ceiling. It’s not a data error. It’s a real physical phenomenon, and NWP models generally underestimate it because they don’t resolve individual cumulus towers at their grid scales.
A Practical Integration Pattern
For solar energy estimation, the most defensible approach is to treat the API value as your GHI input, compute clear-sky GHI independently using the Ineichen-Perez model (well-documented by NREL and accurate enough for most purposes), then compute a clearness index: kt = solar_rad / clear_sky_ghi. From kt you can estimate the diffuse fraction via the Erbs model — a single equation, works well on hourly data — and then transpose to your surface. This is essentially the PVGIS workflow, which has solid validation across European and North American climates.
For construction or outdoor scheduling where you just need a proxy for general sunshine level, using solar_rad as a threshold is serviceable. Roughly: below 100 W/m² is overcast, 100–400 W/m² is partly cloudy, above 600 W/m² is approaching clear-sky depending on latitude and season. Those aren’t precise cutoffs — treat them as UI labelling heuristics, not engineering inputs.
What We Don’t Expose Yet
UV index is already a separate field, derived from a narrow slice of the shortwave spectrum. DNI and DHI are not currently surfaced separately, which means you’re doing your own decomposition if you need them. The GRIB2 variables exist in some of the model outputs we ingest — the holdup is pipeline work and deciding how to version the response schema without breaking existing integrations. It’s on the list.
Photosynthetically active radiation (PAR), which spans 400–700 nm and is what crop modelling applications typically want, is also not a direct field. You can approximate it from GHI — roughly 45–50% of GHI under clear skies, lower under overcast because diffuse radiation is spectrally richer in PAR — but that approximation degrades on cloudy days, which is exactly when PAR limits crop growth and when the error costs you most.
One Thing Worth Checking Right Now
If solar_rad drops to exactly 0.0 at night, that’s correct. If you’re also seeing 0.0 during daytime in conditions that should be partly cloudy, check whether your request is hitting a location with no nearby station and falling through to a model grid point with a data gap. The API response currently doesn’t distinguish a reported zero from an imputed zero. The fastest check: pull is_day alongside solar_rad and compare against your own solar position calculation for that latitude and time. If is_day is 1 and solar_rad is 0.0, the problem is upstream of your code.