Morphemeris DocsLunar Eclipses
GET /v1/eclipses/lunar — Find upcoming or past lunar eclipses, with optional location-based visibility.
Lunar Eclipses
Search for lunar eclipses from a given start date. Returns eclipse phase times (penumbral, partial, total). When observer coordinates are provided, includes a visible flag indicating whether the eclipse is visible from that location.
GET /v1/eclipses/lunar
POST /v1/eclipses/lunarCredit cost: 2
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
datetime | string | One of datetime or jd | — | ISO 8601 UTC datetime |
jd | number | One of datetime or jd | — | Julian Day in UT1 |
lat | number | No | — | Observer latitude (enables visibility check) |
lon | number | No | — | Observer longitude |
alt | number | No | 0 | Observer altitude in meters |
type | string | No | all | Filter: total, partial, penumbral (comma-separated) |
backward | boolean | No | false | Search backward in time |
count | integer | No | 1 | Number of results (1–10) |
Response
{
"data": [
{
"eclipse_type": "total",
"maximum": { "jd": 2460386.458, "datetime": "2025-03-14T06:59:00.000Z" },
"penumbral_begin": { "jd": 2460386.327, "datetime": "2025-03-14T03:51:00.000Z" },
"partial_begin": { "jd": 2460386.389, "datetime": "2025-03-14T05:20:00.000Z" },
"total_begin": { "jd": 2460386.436, "datetime": "2025-03-14T06:27:00.000Z" },
"total_end": { "jd": 2460386.480, "datetime": "2025-03-14T07:31:00.000Z" },
"partial_end": { "jd": 2460386.527, "datetime": "2025-03-14T08:38:00.000Z" },
"penumbral_end": { "jd": 2460386.589, "datetime": "2025-03-14T10:07:00.000Z" }
}
],
"meta": { "..." }
}When observer coordinates are provided, each result includes "visible": true/false.
| Field | Type | Description |
|---|---|---|
eclipse_type | string | total, partial, or penumbral |
maximum | object | Time of greatest eclipse (jd and datetime) |
penumbral_begin | object | Penumbral phase begins |
penumbral_end | object | Penumbral phase ends |
partial_begin | object | Partial phase begins (null for penumbral-only eclipses) |
partial_end | object | Partial phase ends |
total_begin | object | Total phase begins (null for non-total eclipses) |
total_end | object | Total phase ends |
visible | boolean | Whether visible from the given location (local mode only) |
Examples
Next lunar eclipse
curl "https://api.morphemeris.com/v1/eclipses/lunar?datetime=2024-01-01T00:00:00Z" \
-H "Authorization: Bearer morphemeris_live_YOUR_KEY"const res = await fetch(
"https://api.morphemeris.com/v1/eclipses/lunar?datetime=2024-01-01T00:00:00Z",
{ headers: { Authorization: "Bearer morphemeris_live_YOUR_KEY" } }
);
const data = await res.json();import requests
res = requests.get(
"https://api.morphemeris.com/v1/eclipses/lunar",
params={"datetime": "2024-01-01T00:00:00Z"},
headers={"Authorization": "Bearer morphemeris_live_YOUR_KEY"},
)
data = res.json()Visible from London
curl "https://api.morphemeris.com/v1/eclipses/lunar?datetime=2024-01-01T00:00:00Z&lat=51.5074&lon=-0.1278" \
-H "Authorization: Bearer morphemeris_live_YOUR_KEY"