Solar API
Solar geometry for any location on Earth: solar position (azimuth, altitude, zenith), declination, hour angle, equation of time and air mass, at any timestamp from 1900 to 2050. Positions come from JPL DE421, the numerical integration that NREL's SPA approximates.
How this differs from other solar APIs
Energy-yield models, building solar-gain calculations and panel anomaly checks all start from the sun's position. We take the observer's elevation as an input, or look it up for you, where most APIs ignore it or use a coarse lookup. That matters for PV monitoring, greenhouse DLI scheduling, building-energy simulation, and any other work where the length of the sunlight's path through the atmosphere changes the answer.
Endpoint: GET /v1/solar/ ·
Auth: API key (Authorization: Bearer tt_live_…)
Quick start
curl -H "Authorization: Bearer $THIRDTRAIL_KEY" \
"https://thirdtrail.life/v1/solar/?lat=39.7392&lon=-104.9903&elevation=1609×tamp=2026-06-21T18:00:00Z"Denver, CO at 1609 m on the June solstice, at noon local time (18:00 UTC). Returns the sun's azimuth, altitude, zenith, declination, hour angle, equation of time and air mass at that instant.
Tier matrix
| Feature | Free | Developer €19 | Pro €79 | Business €299 | Enterprise |
|---|---|---|---|---|---|
| Calls per day | 100 | 5,000 | 100,000 | 1,000,000 | custom |
| Burst per minute | 10 | 60 | 600 | 3,000 | unlimited |
| Max forecast horizon | 7 d | 30 d | 365 d | 5 y | 50 y |
| Solar position (az / alt / zenith) | ✅ | ✅ | ✅ | ✅ | ✅ |
| Declination, hour angle, EoT, air mass | ✅ | ✅ | ✅ | ✅ | ✅ |
| Clear-sky irradiance (GHI / DNI / DHI) | — | ✅ | ✅ | ✅ | ✅ |
Daily Light Integral (/dli) | — | ✅ | ✅ | ✅ | ✅ |
Sun-path arrays (/path, /range) | — | ✅ | ✅ | ✅ | ✅ |
| Custom turbidity / aerosol | — | — | ✅ | ✅ | ✅ |
Bulk endpoint (/bulk) | — | — | ✅ | ✅ | ✅ |
iCal feed (feed.ics) | — | ✅ | ✅ | ✅ | ✅ |
| Webhooks | — | — | ✅ | ✅ | ✅ |
| Historical queries | — | ✅ (5 y) | ✅ (50 y) | ✅ (100 y) | ✅ (from 1900) |
auto_elevation & auto_timezone | — | — | — | ✅ | ✅ |
Endpoints at a glance
| Endpoint | Method | Purpose |
|---|---|---|
/v1/solar/ | GET | Solar position at one instant, plus clear-sky irradiance on Developer and up. |
/v1/solar/range/ | GET | A time series across a window, at the interval you choose (Developer+). |
/v1/solar/path/ | GET | Sun-path arrays for one date, for shading and facade studies. |
/v1/solar/dli/ | GET | Daily Light Integral for one date or a date range, for greenhouse and crop work. |
/v1/solar/bulk/ | POST | Up to 10 000 (location × timestamp) tuples per request (Pro+). |
/v1/solar/feed.ics | GET | Calendar subscription with solar noon and DLI events. |
/v1/solar/webhooks/ | POST / GET / DELETE | Event subscriptions. Webhooks docs → |
Query parameters
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
lat | float | yes | — | Latitude, decimal degrees, [-90, 90] |
lon | float | yes | — | Longitude, decimal degrees, [-180, 180] |
elevation | float | no | 0 | Metres above sea level. [-500, 9000]. It has a real effect on irradiance and only a second-order effect on position. |
timestamp | datetime | no | now (UTC) | ISO-8601 with timezone offset (e.g. 2026-06-21T18:00:00Z). How far back you can go depends on your plan. |
include | string | no | position | Comma-separated. position always; irradiance / dli on Developer+. |
tz | string | no | — | IANA timezone name. It is only echoed back in resolved.timezone; the computation always runs in UTC. |
utc_offset | string | no | — | Fixed offset ±HH:MM or Z. No DST. Can't be combined with tz. |
auto_timezone | bool | no | false | Business+. Resolves timezone from lat / lon. |
auto_elevation | bool | no | false | Business+. Resolves elevation from lat / lon. |
Without an explicit timestamp, the endpoint computes for
the current instant. The response always echoes the resolved UTC
timestamp at the top level, formatted as ISO-8601 with a Z
suffix (e.g. 2026-05-19T04:21:22Z).
Example response
{
"request": {
"lat": 39.7392, "lon": -104.9903, "elevation_m": 1609,
"timestamp": "2026-06-21T18:00:00Z",
"tz": null, "utc_offset": null,
"auto_elevation": false, "auto_timezone": false,
"include": "position"
},
"resolved": {
"elevation_m": 1609.0, "elevation_source": "user",
"timezone": "UTC", "timezone_source": "default",
"position_model": "JPL DE421",
"plan": "developer"
},
"timestamp": "2026-06-21T18:00:00Z",
"position": {
"azimuth_deg": 156.4231,
"altitude_deg": 69.0851,
"zenith_deg": 20.9149,
"declination_deg": 23.4360,
"hour_angle_deg": -22.1850,
"equation_of_time_min": -1.628,
"air_mass": 1.0700
},
"compute_ms": 12
}
Azimuth is measured clockwise from True North (0° = N, 90° = E,
180° = S, 270° = W). Altitude is measured from the horizon
(0°) to the zenith (90°); negative when the sun is below the
horizon. Air mass is null when the sun is below the horizon.
Conventions
- Azimuth: 0° = North, increasing clockwise. Topocentric, not geocentric.
- Altitude: above the horizon. Includes standard atmospheric refraction below ~5°.
- Hour angle: signed, in
[-180, 180]degrees. Computed from Local Sidereal Time minus apparent right ascension; east longitude positive. - Equation of time: signed, in minutes. Positive when apparent solar time is ahead of mean solar time. Independent of longitude.
- Air mass: Kasten-Young (1989). Defined only above the horizon.
Accuracy notes
- Solar position: numerical integration against the JPL planetary ephemerides, accurate to under an arcsecond for 1900 to 2050. NREL's SPA is a polynomial approximation of that integration, accurate to ±0.0003°; we compute from the integration itself.
- Atmospheric refraction: applied below 5° altitude using Saemundsson's formula. Above 5°, refraction is under 1 arcminute and is not applied separately.
- Equation of time: Meeus polynomial (Chapter 28 of Astronomical Algorithms, 2nd ed.). ±0.5 s accuracy.
- Hour angle: derived from Greenwich Apparent Sidereal Time + east longitude − apparent right ascension. Wrapped to
[-12 h, +12 h). - Air mass: Kasten-Young (1989), which handles a low sun correctly where
1/cos(zenith)is off by an order of magnitude. - Validity range: 1900 to 2050 by default (DE421). Out-of-range timestamps return 400.
Roadmap
Version 2 has everything listed above: solar position, clear-sky irradiance (GHI, DNI, DHI), Daily Light Integral, sun-path arrays, the bulk endpoint, the calendar feed and webhooks. For v3 we are considering spectral decomposition (UV, visible, IR), more clear-sky models (ESRA, Solis), and a tilt, orientation and soiling layer for PV-system modelling. Cloud-affected irradiance is out of scope. The API returns clear-sky theoretical maxima, so pair it with a weather provider for actual conditions.