Solar API

Quick start

curl -H "Authorization: Bearer $THIRDTRAIL_KEY" \
  "https://thirdtrail.life/v1/solar/?lat=39.7392&lon=-104.9903&elevation=1609&timestamp=2026-06-21T18:00:00Z"

Denver, CO at 1609 m, June solstice, solar noon. Returns the sun''s azimuth, altitude, zenith, declination, hour angle, equation of time and air mass at that instant.

Tier matrix

Endpoints at a glance

Query parameters

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: high-precision numerical integration against JPL planetary ephemerides. Sub-arcsecond for all years 1900–2050. NREL''s SPA is a polynomial approximation with ±0.0003° accuracy; we deliver the underlying integration.
• Atmospheric refraction: applied for altitudes < 5° using Saemundsson''s formula. Above 5°, refraction is <1 arcminute and not separately applied.
• 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) — handles low-altitude cases that 1/cos(zenith) gets wrong by an order of magnitude.
• Validity range: 1900–2050 by default (DE421). Out-of-range timestamps return 400.

Roadmap

v2 ships the full feature set listed above: solar position, clear-sky irradiance (GHI/DNI/DHI), Daily Light Integral, sun-path arrays, bulk endpoint, calendar subscription, and webhook event subscriptions. v3 candidates under consideration: spectral decomposition (UV / visible / IR), additional clear-sky models (ESRA, Solis), and a tilt/orientation/soiling layer for downstream PV-system modelling. Cloud-affected irradiance remains out of scope — we deliver deterministic clear-sky theoretical maxima; pair with a weather provider for actuals.

Start using it

Create a free account