Caelus3,462 checksGitHubv0.25.0MIT
Guides

Eclipses

Caelus provides functions to answer three eclipse questions: when eclipses occur within a date range, where a solar eclipse path crosses Earth, and what a viewer at a specific location sees. Every eclipse helper runs on the embedded data tier using the same Sun and Moon calculations as charts.

TypeScript
import {
  Engine, julianDay, solarEclipses, solarEclipseWhere, solarEclipseLimits,
  solarEclipseLocal, lunarEclipses, lunarEclipseLocal,
} from "caelus";
import { embeddedData } from "caelus/data-embedded";

const engine = new Engine(embeddedData);

// Reads a Julian Day as a UTC timestamp.
const utc = (jd) => new Date((jd - 2440587.5) * 86400000).toISOString();

Finding eclipses in a date range

solarEclipses and lunarEclipses return every eclipse occurring between two Julian Days in chronological order:

TypeScript
solarEclipses(engine, julianDay(2024, 1, 1), julianDay(2027, 1, 1))
  .map((e) => [utc(e.tMax), e.type, e.gamma]);
Greatest eclipse (UT)TypeGamma
2024-04-08 18:17:23total0.3433
2024-10-02 18:45:00annular0.3506
2025-03-29 10:47:39partial1.0413
2025-09-21 19:41:49partial1.0650
2026-02-17 12:12:00annular0.9743
2026-08-12 17:45:46total0.8978

Each solar eclipse record includes tMax, type (total, annular, hybrid, or partial), gamma, and the global begin and end timestamps. Gamma measures the distance from the Moon's shadow axis to Earth's center in Earth radii; when gamma exceeds roughly 1, the shadow axis misses Earth and the eclipse is partial everywhere.

A lunar eclipse record provides tMax, type (total, partial, or penumbral), umbral and penumbral magnitudes, and start/end times for every phase reached. During the total lunar eclipse of 14 March 2025, tMax falls at 06:58:41 UT with an umbral magnitude of 1.178 and totality lasting from 06:25:58 to 07:31:21 UT.

Locating the solar eclipse path

For a solar eclipse, solarEclipseWhere returns the geographic coordinates directly beneath the shadow axis at a given timestamp, while solarEclipseLimits adds the northern and southern bounds of the central path alongside its width in kilometers:

TypeScript
const [eclipse] = solarEclipses(engine, julianDay(2024, 4, 1), julianDay(2024, 5, 1));

solarEclipseWhere(engine, eclipse.tMax);
// { lat: 25.30, lonEast: -104.17 }   in Mexico, near Torreón
TypeScript
solarEclipseLimits(engine, eclipse.tMax).widthKm;
// 198.98

Sampling timestamps from begin to end traces the full path across Earth. Both functions return null when no central eclipse touches the surface at that timestamp.

Local circumstances for an observer

Pass observer coordinates to solarEclipseLocal to calculate the local eclipse type, magnitude, solar disc obscuration, and four contact times:

TypeScript
solarEclipseLocal(engine, eclipse.tMax, 32.78, -96.80);   // Dallas
FieldDallasNew York
typetotalpartial
magnitude1.0560.910
obscuration1.0000.898
c1, partial begins17:23:24 UT
c2, totality begins18:40:45 UT
maxTime18:42:43 UT19:25:40 UT
c3, totality ends18:44:41 UT
c4, partial ends20:02:45 UT

In Dallas, totality lasts 236 seconds. Outside the eclipse footprint, type is "none" and the contact times are null.

Because a lunar eclipse happens simultaneously everywhere on Earth's night side, the local question is simply whether the Moon is above the horizon. lunarEclipseLocal returns the Moon's altitude and a visible boolean: at greatest eclipse on 14 March 2025, the Moon stands 44° above the horizon in New York and 5° below it in London.

Accuracy

Times of greatest eclipse match Swiss Ephemeris within 9 seconds, and all 92 lunar eclipses and 89 solar eclipses between 1990 and 2030 classify with zero type mismatches. Contact times typically agree within 15 seconds (widening to minutes during grazing eclipses), and sub-shadow ground coordinates stay within 10 km. Detailed benchmarks appear on Validation.

This accuracy reliably establishes whether a city sees totality and its duration within a few seconds, though observers situated right on the edge of a path should consult an official Besselian-element map where a single kilometer can decide totality.

Start building

Quickstart →