Search for solar and lunar eclipses — past or future, global or at a specific location.

Find Eclipses

Use the /v1/eclipses/solar and /v1/eclipses/lunar endpoints to search for eclipses starting from any date. Add observer coordinates to get local visibility data.

Find the next solar eclipse

Bash

curl "https://api.morphemeris.com/v1/eclipses/solar?\
datetime=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

This returns the next global solar eclipse after the given date — the April 8, 2024 total solar eclipse.

Check local visibility

Add lat and lon to find out what an observer at that location would see, including magnitude and obscuration:

Bash

curl "https://api.morphemeris.com/v1/eclipses/solar?\
datetime=2024-01-01T00:00:00Z\
&lat=30.2672\
&lon=-97.7431" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

The response includes magnitude (fraction of the Sun's diameter covered) and obscuration (fraction of the Sun's area covered), plus contact times as seen from that location.

Find multiple eclipses

Use count to get several results at once — useful for building eclipse calendars:

javascript

const res = await fetch(
  "https://api.morphemeris.com/v1/eclipses/solar?" +
    "datetime=2024-01-01T00:00:00Z&count=5",
  { headers: { Authorization: `Bearer ${apiKey}` } }
);
const { data } = await res.json();

for (const eclipse of data) {
  console.log(`${eclipse.eclipse_type} — ${eclipse.maximum.datetime}`);
}
// total — 2024-04-08T18:17:20.379Z
// annular — 2024-10-02T...
// ...

Filter by type

Only interested in total eclipses? Use the type filter:

Bash

curl "https://api.morphemeris.com/v1/eclipses/solar?\
datetime=2024-01-01T00:00:00Z\
&type=total\
&count=3" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

You can combine types with commas: type=total,annular.

Search backward

Find the most recent eclipse before a date:

Bash

curl "https://api.morphemeris.com/v1/eclipses/lunar?\
datetime=2024-06-01T00:00:00Z\
&backward=true" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

Lunar eclipse phases

Lunar eclipse responses include phase timing — when the penumbral, partial, and total phases begin and end:

javascript

const { data } = await res.json();
const eclipse = data[0];

if (eclipse.total_begin) {
  console.log(`Totality: ${eclipse.total_begin.datetime} to ${eclipse.total_end.datetime}`);
} else if (eclipse.partial_begin) {
  console.log(`Partial phase: ${eclipse.partial_begin.datetime} to ${eclipse.partial_end.datetime}`);
} else {
  console.log(`Penumbral only: ${eclipse.penumbral_begin.datetime} to ${eclipse.penumbral_end.datetime}`);
}

Tips

Solar eclipse searches cost 3 credits; lunar cost 2. The count parameter doesn't change the cost.
Local solar eclipse calculations are more expensive computationally but cost the same number of credits.
For an eclipse calendar app, search with count=10 and cache the results — eclipse dates don't change.
See Eclipses for background on eclipse types and contact times.

Find Eclipses

On this page