Eclipses

Solar and lunar eclipses 2020–2040 — types, times of maximum, magnitudes, lunar durations and greatest-eclipse points, from the same verified engine as the eclipse maps.

GET https://theshia.org/api/v1/eclipses

Parameters

kind optional values: "solar" · "lunar".
type optional values: "total" · "annular" · "hybrid" · "partial" · "penumbral".
from optional start of the window — YYYY or YYYY-MM-DD (dataset covers 2020 to 2040).
to optional end of the window — YYYY (through that year's end) or YYYY-MM-DD.
upcoming optional 1 to 24 — the next N eclipses from today, each with daysUntil. Not combinable with from/to.
calendar default: moonsighting reckoning for the returned Hijri dates — values: "moonsighting" · "iran".

Response per eclipse: kind, type, utc (maximum, ISO 8601), gamma, magnitude (partial-solar / umbral-lunar; null otherwise), penumbralMag + durationsMin { penumbral, partial, total } for lunar, greatest { lat, lon, central } for solar, and hijri { hy, hm, hd }.
Computed by this site's fresh Meeus ch. 49/54 engine, verified against the NASA GSFC catalog (times of maximum within ~1 minute; penumbral grazes under magnitude ~0.005 fall below the method's noise floor).
Penumbral lunar eclipses are generally imperceptible and commonly not counted for Salat al-Ayat.

Open live example ↗

Code samples

curl

curl "https://theshia.org/api/v1/eclipses?upcoming=4"

JavaScript

const res = await fetch("https://theshia.org/api/v1/eclipses?upcoming=4");
const data = await res.json();

Python

import requests

data = requests.get("https://theshia.org/api/v1/eclipses?upcoming=4").json()

Rate limits & fair use

Responses are cached hard at the edge — please cache on your side too. Uncached requests are limited to 100 per minute per IP; oversized requests (over 496 day×method computations) are rejected. Free for community use, no uptime guarantee.