Docs › Celestial event calendar (eclipses, stations, lunations)

Celestial event calendar (eclipses, stations, lunations)

Solar and lunar eclipses, planetary stations, lunations, separations, longitude crossings and declination events between two dates (1800-2200), to the minute.

POST https://astro-agent.dev/v1/astronomy/events · $0.25 per call · MCP tool celestial_events · Try it in the playground

A calendar of exact events between two dates: solar and lunar eclipses (type and magnitude), stations (retrograde / direct), new and full Moons and quarters, separations between planets at chosen angles, ecliptic longitudes crossing multiples of 30 degrees, equal / opposite declinations, and declinations passing the obliquity of the ecliptic. Geocentric or heliocentric. Each event has its UTC minute, a unix timestamp and a stable key.

Authentication

Send your key in the X-Credits-Token header. A free key comes with the Free plan (1,000 calls a month, up to 100 of them on the premium data routes). Without a key, each client gets 1 free call on the $0.01-0.02 routes; past it the API answers 402 with an x402 / MPP pay-per-call offer.

Parameters

ParameterTypeRequiredDefaultDescription
startstringyesFirst UTC date, YYYY-MM-DD, 1800..2199. Example: '2024-01-01'.
endstringyesLast UTC date, YYYY-MM-DD, at most 366 days after start (inclusive).
perspectivestring: geocentric | heliocentric"geocentric"'geocentric' (default) or 'heliocentric'. Heliocentric gives separations and longitude crossings only (no stations, lunations or eclipses).
bodiesarray of string (sun, mercury, venus, earth, mars, jupiter, saturn, uranus, neptune, pluto)Planets searched. Default: Sun..Pluto (geo), Mercury..Pluto with Earth (helio).
include_moonbooleanfalseAlso the Moon's separations, longitude crossings and declination events (geocentric only; many more events).
includearray of string (declination, declination_beyond_obliquity, eclipse, longitude_crossing, lunation, separation, station)Event types. Default: all that apply to the perspective. 'separation': two bodies reach one of the 'angles'; 'longitude_crossing': a body's ecliptic longitude crosses a multiple of 30 degrees; 'declination': equal or opposite declinations; 'declination_beyond_obliquity': |declination| passes the obliquity of the ecliptic; 'station', 'lunation', 'eclipse'.
anglesvalueSeparation angles in degrees, 'all' or a list from [0, 30, 45, 60, 72, 90, 120, 135, 144, 150, 180]. Default: [0, 60, 90, 120, 180].

Example request

curl

curl -s https://astro-agent.dev/v1/astronomy/events \
  -H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start": "2026-01-01", "end": "2026-12-31", "include": ["eclipse", "station"]}'

Python

import os
import requests

body = {'start': '2026-01-01', 'end': '2026-12-31', 'include': ['eclipse', 'station']}
r = requests.post("https://astro-agent.dev/v1/astronomy/events", json=body,
                  headers={"X-Credits-Token": os.environ.get("ASTRO_AGENTS_KEY", "")}, timeout=60)
if not r.ok:
    raise SystemExit(f"{r.status_code}: {r.text}")
data = r.json()

for ev in data["result"]["events"]:
    what = ev.get("kind") or ev.get("body") or ev.get("phase") or "-".join(ev.get("bodies", []))
    detail = ev.get("eclipse_type") or ev.get("turns") or ev.get("angle") or ev.get("relation") or ""
    print(ev["exact_utc"], ev["type"], what, detail)
print("result_sha256:", data["meta"]["result_sha256"])

JavaScript (Node 18+)

// Node 18+ (built-in fetch). Save as call.mjs and run: node call.mjs
const body = {"start": "2026-01-01", "end": "2026-12-31", "include": ["eclipse", "station"]};
const res = await fetch("https://astro-agent.dev/v1/astronomy/events", {
  method: "POST",
  headers: {"X-Credits-Token": process.env.ASTRO_AGENTS_KEY ?? "", "Content-Type": "application/json"},
  body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const data = await res.json();

for (const ev of data.result.events) {
  const what = ev.kind || ev.body || ev.phase || (ev.bodies || []).join("-");
  console.log(ev.exact_utc, ev.type, what, ev.eclipse_type || ev.turns || ev.angle || ev.relation || "");
}
console.log("result_sha256:", data.meta.result_sha256);

Example response

A real response to the request above (lists shortened to 3 items). The same request always returns this result_sha256:

22795e28a7daefaed2f66fe036dbc1e79a5df87c7c6b5626e202ed3ca118addf

{
  "endpoint": "astronomy/events",
  "result": {
    "events": [
      {
        "type": "station",
        "body": "uranus",
        "turns": "direct",
        "longitude": 57.459783,
        "exact_utc": "2026-02-04T00:15Z",
        "timestamp": 1770164100,
        "key": "station:uranus:direct:2026-02-04T00:15Z"
      },
      {
        "type": "eclipse",
        "kind": "solar",
        "gamma": -0.974274,
        "umbral_radius_earth_radii": 0.011153,
        "central": true,
        "eclipse_type": "annular",
        "exact_utc": "2026-02-17T12:12Z",
        "timestamp": 1771330320,
        "key": "eclipse:solar:annular:2026-02-17T12:12Z"
      },
      {
        "type": "station",
        "body": "mercury",
        "turns": "retrograde",
        "longitude": 352.565325,
        "exact_utc": "2026-02-26T06:48Z",
        "timestamp": 1772088480,
        "key": "station:mercury:retrograde:2026-02-26T06:48Z"
      }
    ],
    "counts": {
      "station": 18,
      "eclipse": 4
    },
    "settings": {
      "start": "2026-01-01",
      "end": "2026-12-31",
      "perspective": "geocentric",
      "bodies": [
        "sun",
        "mercury",
        "venus"
      ],
      "include_moon": false,
      "frame": "geocentric apparent, true ecliptic and equinox of date; declinations on the true equator of date",
      "eclipses": "solar: shadow-axis geometry from DE440, types by Meeus ch. 54 (gamma, umbral radius u); lunar: Skyfield eclipselib (Danjon-enlarged shadow); time = greatest eclipse",
      "timestamp": "unix seconds of exact_utc (UTC minute), to join on candle open times",
      "types": [
        "station",
        "eclipse"
      ],
      "separation_angles": [
        0,
        60,
        90
      ],
      "precision": "event times +/- 1 minute (UTC); stations and slow declination crossings are flat, so their minute is the least sharp",
      "longitude_reference": "ecliptic longitude from the true equinox of date (0-360 degrees)"
    }
  },
  "meta": {
    "engine": "astro-agents/1.10.0",
    "ephemeris": "NASA/JPL DE440 (1800-01-01..2200-01-01)",
    "astronomy_library": "skyfield/1.55",
    "frame": "geocentric apparent positions, true ecliptic and equinox of date (IAU 2006/2000A)",
    "deterministic": true,
    "llm_used": false,
    "input_sha256": "89872860c166a01f65ab4e202381fb2fe5c270970b4af5175e36330f8f1fc659",
    "result_sha256": "22795e28a7daefaed2f66fe036dbc1e79a5df87c7c6b5626e202ed3ca118addf",
    "reproducibility": "result_sha256 = SHA-256 of the result serialized as JSON with sorted keys, no whitespace, UTF-8, floats rounded to 6 decimals. Same input + same engine version => same hash."
  }
}

Response fields

FieldTypeDescription
result.settingsobjectSettings applied: date range, perspective, event types, bodies, separation angles, frame, longitude reference, precision and the eclipse method.
result.eventsarrayEvents in time order, each with 'type' (eclipse, lunation, station, separation, longitude_crossing, declination, declination_beyond_obliquity), its details, 'exact_utc', unix 'timestamp' and a stable 'key'.
result.countsobjectNumber of events of each type.
endpointstringThe route that computed it.
meta.input_sha256stringSHA-256 of the canonical request.
meta.result_sha256stringSHA-256 of the canonical result: POST /v1/verify recomputes it.
meta.engine_version / meta.ephemerisstringEngine release and ephemeris (NASA/JPL DE440).

CSV

Add ?format=csv to get the table of the result as CSV (gzip when your client sends Accept-Encoding: gzip): POST https://astro-agent.dev/v1/astronomy/events?format=csv. Same price and quota as JSON; the X-Result-SHA256 header is the hash of the JSON result the CSV is a view of. Long ranges in one file: bulk export.

Errors

400 for an invalid input (never charged), 401 / 403 for a key problem, 402 to pay, 429 for a quota or rate limit: see the error reference.