Morphemeris DocsEclipses
How solar and lunar eclipses work, and how the API models them.
Eclipses
An eclipse occurs when the Sun, Moon, and Earth align so that one body casts a shadow on another. The Morphemeris API can search for both solar and lunar eclipses, returning precise timing and geometry data.
Solar eclipses
A solar eclipse happens when the Moon passes between the Sun and Earth, blocking some or all of the Sun's light. They occur at new Moon — but not every new Moon, because the lunar orbit is tilted about 5° to the ecliptic. Eclipses only happen when the new Moon falls near a node (where the Moon's orbit crosses the ecliptic plane).
Types
| Type | What happens | How it looks |
|---|---|---|
| Total | Moon completely covers the Sun's disk | Dark sky, visible corona |
| Annular | Moon is too far from Earth to fully cover the Sun | Bright ring ("annulus") around the Moon |
| Partial | Moon only covers part of the Sun's disk | Crescent Sun |
| Annular-total | Eclipse shifts between annular and total along its path | Rare hybrid type |
Global vs. local
The API supports two modes:
- Global (no location) — Returns the eclipse's overall timing: when it begins and ends on Earth's surface, and the moment of greatest eclipse. Useful for finding when eclipses happen.
- Local (with
lat/lon) — Returns timing as seen from a specific location, plus magnitude (fraction of the Sun's diameter covered) and obscuration (fraction of the Sun's area covered). Useful for determining what an observer would see.
See the /v1/eclipses/solar reference for parameters and response fields.
Lunar eclipses
A lunar eclipse happens when the Earth passes between the Sun and Moon, casting Earth's shadow on the Moon. They occur at full Moon, again only when the full Moon is near a node.
Types
| Type | What happens | Visibility |
|---|---|---|
| Total | Moon passes entirely through Earth's umbra | Moon turns deep red ("blood moon") |
| Partial | Moon partially enters the umbra | Part of the Moon darkens |
| Penumbral | Moon passes through Earth's penumbra only | Subtle dimming, often hard to notice |
Unlike solar eclipses, a lunar eclipse is visible from anywhere on Earth where the Moon is above the horizon during the event. The API returns phase timing — when the penumbral, partial, and total phases begin and end — so you can determine exactly what's happening at any moment during the eclipse.
See the /v1/eclipses/lunar reference for parameters and response fields.
Eclipse frequency
On average, there are 2-3 solar eclipses and 2-3 lunar eclipses per year. Total solar eclipses visible from any specific location are much rarer — roughly once every 375 years for a given point on Earth.
Contact times
Eclipse timing is described in terms of contacts — the moments when the edges of the two disks touch:
- First contact (C1) — Eclipse begins; the Moon's edge first touches the Sun's (solar) or enters the penumbra (lunar)
- Second contact (C2) — Totality or annularity begins (total/annular eclipses only)
- Maximum — Greatest eclipse; maximum coverage
- Third contact (C3) — Totality or annularity ends
- Fourth contact (C4) — Eclipse ends; the disks fully separate
Not all contacts occur for every eclipse. A partial solar eclipse has only C1, maximum, and C4.