🗓️Events
Eclipses and apsides for the observer's location
Returns the events falling between two instants, as seen from the observer's location.
Two kinds are reported, told apart by type:
type
What it is
Bodies
lunar_eclipse, solar_eclipse
The Earth's shadow on the Moon, or the Moon's on us
Sun and Moon
apsis
Nearest to, or farthest from, the Earth
All
Returns the events falling between from and to, as seen from the
observer's location.
Eclipses are reported for the Sun and the Moon, with the altitude of the body at each contact so that it is clear how much of the event happens above the horizon. A solar eclipse is reported as this observer sees it, so the same eclipse is total from one place and partial from another.
Apsides are reported for every body: the moments its distance from the Earth stops changing direction. They alternate between perigee and apogee. For a planet the perigee is when it appears largest and brightest, falling within days of opposition.
v2 offered only eclipses, and only for the Sun and the Moon.
The application key, sent as Authorization: Bearer <key>. Keys are
never accepted in the query string, where they would be recorded in
logs and browser history.
Latitude of the observer, in degrees, positive north.
51.4779Longitude of the observer, in degrees, positive east.
-0.0015Height of the observer above sea level, in metres. Defaults to sea level. The upper bound covers the highest permanent observatories.
0First instant to sample, as an ISO 8601 date or date-time. A bare date means midnight UTC on that date.
2024-06-21T00:00:00ZLast instant to sample. Must not precede from.
2024-06-22T00:00:00ZIANA zone the returned instants are expressed in. auto derives it
from the observer's coordinates, which is what v2 always did and
remains the default. UTC is the unambiguous choice.
autoExample: autoEvents for each requested body.
The request could not be parsed.
The application key was missing or not recognised.
The request was understood but a parameter was unacceptable.
GET /api/v3/events?latitude=51.4779&longitude=-0.0015&from=2024-06-21T00%3A00%3A00Z&to=2024-06-22T00%3A00%3A00Z HTTP/1.1
Host: api.astronomyapi.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"meta": {
"observer": {
"latitude": 1,
"longitude": 1,
"elevation": 1
},
"timezone": "text",
"window": {
"from": "2026-01-01T00:00:00.000Z",
"to": "2026-01-01T00:00:00.000Z"
}
},
"data": [
{
"body": {
"id": "sun",
"name": "Mars"
},
"events": [
{
"type": "lunar_eclipse",
"kind": "penumbral",
"time": "2026-01-01T00:00:00.000Z",
"altitude": 1,
"contacts": {
"penumbralStart": {
"time": "2026-01-01T00:00:00.000Z",
"altitude": 1
},
"partialStart": {
"time": "2026-01-01T00:00:00.000Z",
"altitude": 1
},
"totalStart": {
"time": "2026-01-01T00:00:00.000Z",
"altitude": 1
},
"totalEnd": {
"time": "2026-01-01T00:00:00.000Z",
"altitude": 1
},
"partialEnd": {
"time": "2026-01-01T00:00:00.000Z",
"altitude": 1
},
"penumbralEnd": {
"time": "2026-01-01T00:00:00.000Z",
"altitude": 1
}
},
"obscuration": 1,
"rise": "2026-01-01T00:00:00.000Z",
"set": "2026-01-01T00:00:00.000Z"
}
]
}
]
}Eclipses
Each contact carries the altitude of the body at that moment, so it is clear how much of the event actually happens above the horizon. A solar eclipse is reported as this observer sees it, so the same eclipse is total from one place and partial from another.
totalStart and totalEnd are null for an eclipse that does not reach totality where the observer stands.
Apsides
A body's distance from the Earth rises and falls, and an apsis is a moment it turns around. They alternate: perigee, apogee, perigee, and so on.
For the Moon these are the familiar ones, about 13.8 days apart, and the reason some full Moons look larger than others.
For a planet the perigee is when it appears largest and brightest. It falls within a few days of opposition for the outer planets, and of inferior conjunction for Mercury and Venus. Jupiter's perigee on 6 December 2024 sat one day before its opposition; Saturn's on 8 September 2024 fell on the same day as its own.
The Sun's perigee is the Earth's perihelion, in early January, when the Earth is about 0.9833 AU from the Sun rather than the 1.0167 AU it reaches in July.
Examples
Everything visible from London in 2026:
Only eclipses:
When Mars is next closest, and how far away that is:
Changes from v2
Apsides are new. v2 had no notion of them.
Every body has events now. v2 accepted only sun and moon, because eclipses were all it knew about.
type and kind are separate. v2 returned a single string such as partial_lunar_eclipse, which had to be split before either half could be used. v3 returns type: "lunar_eclipse" and kind: "partial".
The contact names are consistent. v2 named the beginning and end of totality fullStart and fullEnd for a lunar eclipse but totalStart and totalEnd for a solar one, for the same idea. v3 uses totalStart and totalEnd throughout, and calls the block contacts rather than eventHighlights.
Last updated