Methodology

Computation engine

• Library: Skyfield — rise/set/transit via almanac.find_risings/find_settings/find_transits, and the four twilight boundaries via almanac.dark_twilight_day.
• Ephemeris: JPL DE421 (de421.bsp), which bounds the supported range to roughly 1900–2050.
• Observer model: WGS-84 geodetic position (wgs84.latlon), parallax-corrected for elevation.

Refraction & the horizon

• Standard refraction: a fixed 34′ (−0.5667°) depression below the geometric horizontal — the conventional value for rise/set.
• Elevation correction (our differentiator): for an observer at height h we lower the horizon by the geometric dip arccos(R / (R + h)) (mean Earth radius R = 6 371 000 m), so rises happen earlier and sets later than at sea level. At sea level the horizon is simply −0.5667°.
• Twilight angles (sun-centre depression): civil −6°, nautical −12°, astronomical −18°.
• Polar cases: always-up / always-down are detected and reported via the status field rather than returned as errors.

Accuracy per field

“Sub-arcsecond” describes the astronomical position of the bodies from the ephemeris model — it is not the clock-time accuracy of the events. Event times are dominated by atmospheric refraction and your local horizon, so our published figures are:

• Rise / set: ~±1 minute
• Transit (solar noon): ~±30 seconds
• Twilight boundaries: ~±2 minutes
• Moon illumination fraction: ~±0.001

Larger discrepancies versus other sources almost always come from a different horizon convention (geometric vs. centre vs. upper-limb of the disc) or from local terrain that no global model captures. We validate against published U.S. Naval Observatory rise/set tables internally; we do not yet publish a live benchmark.

Versioning

Any change to the underlying ephemeris data or the refraction model is a breaking change and would ship as a new major API version (e.g. /v2/ephemerides/) — never silently within /v1/.