Ask a solar developer what data their site screening tool needs and irradiance comes up immediately. Ask which irradiance metric they need and the answers diverge fast. GHI for yield modeling, DNI for tracking systems, DHI for diffuse-dominated climates, POA for plane-of-array comparisons — each serves a different calculation, and conflating them produces yield estimates that are off by 10 to 25 percent depending on system tilt and tracker configuration.
This is a practical guide to the three primary irradiance components, when your application needs each, and how Derapi's irradiance endpoints return them.
The Three Components: What They Measure
Global Horizontal Irradiance (GHI) measures the total solar radiation on a horizontal surface, combining both direct beam and diffuse sky radiation. GHI is the most commonly published metric because it's the easiest to measure with a standard pyranometer and because most large-scale irradiance databases — NREL's NSRDB, Solargis, SolarAnywhere — report it as their primary variable.
Direct Normal Irradiance (DNI) measures only the beam component of solar radiation, received from the direction of the sun on a surface that is always perpendicular to the sun's rays (hence "normal"). DNI is what concentrating solar power (CSP) systems and high-concentration photovoltaics (HCPV) depend on almost entirely, and it's a significant factor in the performance of single-axis and dual-axis tracking PV systems.
Diffuse Horizontal Irradiance (DHI) measures the scattered sky radiation on a horizontal surface — what reaches the ground after being scattered by clouds, aerosols, and the atmosphere, minus the direct beam component. In overcast climates (Pacific Northwest, UK, Northern Europe), DHI often represents 50–70% of total irradiance on cloudy days and is a meaningful determinant of annual yield for fixed-tilt systems at those latitudes.
The relationship between them is: GHI = DNI × cos(solar zenith angle) + DHI. This decomposition is important because your application may receive one component from a sensor network and need to derive the others.
What Your Application Actually Needs by Use Case
The right metric depends on what you're building:
- Site screening for fixed-tilt rooftop PV — GHI is sufficient. Fixed-tilt systems don't concentrate DNI, and for a quick go/no-go screen, comparing GHI across candidate sites in the same region is a valid proxy for relative yield potential.
- Yield modeling with a PVWatts-style calculation — You need GHI, DNI, and DHI separately, plus ambient temperature and wind speed. PVWatts v8 (NREL's public model) takes all five inputs and applies the Perez transposition model to calculate plane-of-array irradiance at your specified tilt and azimuth.
- Single-axis tracker performance — DNI matters more here. As tracker tilt angle follows the sun, the system captures a higher proportion of the direct beam component. In high-DNI climates (southwestern US, Atacama, MENA), the yield advantage of tracking over fixed tilt is primarily driven by DNI capture, not GHI.
- Diffuse-dominated climates (Portland, Seattle, UK, Northern Europe) — DHI is the variable to watch. In Portland, OR, average annual DHI runs around 35–45% of GHI due to the high cloud fraction. A fixed-tilt system at 30° south at 45° latitude in Portland will have a meaningfully different energy ratio than the same system in Phoenix, and this difference is captured in DHI, not GHI alone.
How Derapi Returns Irradiance Data
Derapi's irradiance endpoint returns all three components in a single response, along with the decomposition metadata:
GET /v1/solar/irradiance?lat=45.5051&lon=-122.6750&period=7d&interval=1hThe response body includes ghi_wh_m2, dni_wh_m2, and dhi_wh_m2 for each hourly interval, plus clearsky_ghi for comparison against modeled clear-sky values. The clearsky_ghi field is useful for cloud-fraction calculations and for identifying whether a given period is anomalously shaded versus a normal seasonal pattern.
The endpoint also returns temp_ambient_c and wind_speed_ms in the same response, eliminating the need for a separate weather API call. For a PVWatts-equivalent calculation, this single Derapi call returns all the inputs you need.
For historical data, the period parameter accepts ISO 8601 date ranges: period=2024-01-01/2024-12-31 returns the full prior year at your specified interval. For a 10-year typical meteorological year (TMY) dataset — the standard input for bankable yield assessments — use period=tmy, which returns the TMY3 or TMY4 dataset appropriate for that location from NREL's NSRDB.
A Real Calculation: Portland Rooftop vs. Medford, OR
To make this concrete, consider an EPC team evaluating two candidate commercial rooftop sites in Oregon: one in Portland (45.5°N, maritime climate, high cloud fraction) and one in Medford (42.3°N, high desert, clear-sky dominated). Both sites have the same proposed 500 kW DC system at 15° tilt, south-facing.
A query to /v1/solar/irradiance for a recent full year returns the following approximate annual totals:
| Location | GHI (kWh/m²/yr) | DNI (kWh/m²/yr) | DHI (kWh/m²/yr) |
|---|---|---|---|
| Portland, OR | ~1,350 | ~1,100 | ~580 |
| Medford, OR | ~1,750 | ~1,900 | ~390 |
Note that Medford's DNI exceeds its GHI. That's physically valid — it reflects a high proportion of direct beam radiation in a low-aerosol, high-altitude clear-sky climate. The DHI is correspondingly lower. Portland's much higher DHI fraction (43% of GHI vs. 22% for Medford) means its yield is less sensitive to tilt angle optimization — there's less directional bias in the diffuse component — and more sensitive to module temperature (which is lower in Portland, partially offsetting the lower irradiance).
Your application can expose exactly this comparison to users without requiring them to understand the underlying decomposition. Derapi returns the numbers; your yield model does the calculation; your UX shows the answer.
When GHI Alone is Misleading
We're not saying GHI is an insufficient metric for all purposes. For broad regional screening — comparing sites within the same climate zone, all with similar system configurations — GHI differences are a reliable ranking signal. The problem arises when your application compares sites across climate boundaries or when the system configuration varies (fixed-tilt vs. tracking vs. bifacial).
A bifacial module captures rear-side irradiance that depends heavily on ground albedo and DHI. In a snowy high-latitude climate, winter albedo can significantly boost rear-side yield — a factor that GHI-only models completely miss. If your application is sizing bifacial systems, you need DHI and an albedo parameter, which Derapi returns as albedo_fraction in the irradiance response.
Similarly, if your app is comparing a coastal California site (high DHI fraction due to marine layer) with a Central Valley site 80 miles inland (low DHI, high DNI), using GHI alone as the yield proxy will underestimate the coastal site's performance for fixed-tilt systems and overestimate it for tracking systems.
Forecasts vs. Actuals: What the 7-Day Endpoint Returns
Derapi's irradiance endpoint supports both historical actuals and short-term forecasts. The period=7d parameter returns a 7-day forward forecast derived from NWP (numerical weather prediction) model output, blended with satellite-derived irradiance nowcasting for the first 4–6 hours. Forecast accuracy degrades with lead time: 1-hour forecasts typically achieve a skill score (vs. persistence) of 15–30% improvement in mean absolute error; 24-hour forecasts improve on persistence by roughly 5–15% depending on location and season.
The practical use case for the forecast endpoint is smart charging or storage dispatch: an EVSE operator or battery energy storage (BESS) controller needs to know how much solar generation to expect in the next 6–24 hours to optimize dispatch decisions. For that use case, GHI forecast is usually sufficient — you're estimating generation potential, not sizing a system. Request ?fields=ghi_forecast to reduce response payload when you don't need DNI and DHI.
For long-term yield assessments, always use the TMY dataset, not a recent actuals period. A single year can be anomalously high or low due to El Niño/La Niña cycles or unusual wildfire smoke aerosol loading. TMY averages across a representative multi-year period and is the appropriate baseline for a financial model or debt financing yield assessment.