Docs › Local circumstances of solar and lunar eclipses

Local circumstances of solar and lunar eclipses

For a place: every solar and lunar eclipse between two dates with its local circumstances: whether and how it is seen, contact times, magnitude, obscuration, duration and the Sun's or Moon's altitude.

POST https://astro-agent.dev/v1/astronomy/eclipse-local · $0.10 per call · MCP tool local_eclipse · Try it in the playground

For eclipse chasers, planetariums, schools and travel apps: solar eclipses from the place's own viewpoint (local type: total, annular, partial or none; contacts C1, C2, maximum, C3, C4 with the Sun's altitude and azimuth; magnitude, obscuration, duration, duration of totality or annularity) and lunar eclipses (penumbral and umbral contacts P1, U1, U2, maximum, U3, U4, P4 with the Moon's altitude, umbral and penumbral magnitude, durations), each marked visible when the body is above the horizon. Matches NASA's predictions to a few seconds (2024-04-08 at Dallas, 2025-03-14 lunar eclipse).

Authentication

Send your key in the X-Credits-Token header. A free key comes with the Free plan (10,000 calls a month on the core routes, 100 a month 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-01-08..2199-12-30).
endstringyesLast UTC date, YYYY-MM-DD, at most 366 days after start.
latitudenumberyesDecimal degrees, north positive.
longitudenumberyesDecimal degrees, east positive.
elevation_mnumber0Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled).
timezonestringIANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules).
kindsarray of string (solar, lunar)Eclipse kinds to return. Default: both.

Example request

curl

curl -s https://astro-agent.dev/v1/astronomy/eclipse-local \
  -H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start": "2024-04-01", "end": "2024-04-30", "latitude": 32.7767, "longitude": -96.797}'

Python

import os
import requests

body = {'start': '2024-04-01', 'end': '2024-04-30', 'latitude': 32.7767, 'longitude': -96.797}
r = requests.post("https://astro-agent.dev/v1/astronomy/eclipse-local", 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 e in data["result"]["eclipses"]:
    print(e["kind"], e["global_type"], "-> here:", e.get("local_type", "lunar"), e.get("magnitude"))
    for c in e.get("contacts", []):
        print("   ", c["contact"], c["local"])
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": "2024-04-01", "end": "2024-04-30", "latitude": 32.7767, "longitude": -96.797};
const res = await fetch("https://astro-agent.dev/v1/astronomy/eclipse-local", {
  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 e of data.result.eclipses) {
  console.log(e.kind, e.global_type, "-> here:", e.local_type || "lunar", e.magnitude);
  for (const c of e.contacts || []) console.log("   ", c.contact, c.local);
}
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:

b5912568c815c23d885ee764fb2f2bd37d29c87e47af3af2333a931ad3858f07

{
  "endpoint": "astronomy/eclipse-local",
  "result": {
    "subject": {
      "location": {
        "latitude": 32.7767,
        "longitude": -96.797,
        "elevation_m": 0.0
      },
      "timezone": "America/Chicago",
      "timezone_source": "resolved_from_coordinates"
    },
    "settings": {
      "start": "2024-04-01",
      "end": "2024-04-30",
      "kinds": [
        "solar",
        "lunar"
      ],
      "conventions": {
        "solar": "topocentric apparent discs of the Sun (R = 696,340 km) and the Moon (R = 1,737.4 km, smooth limb); C1/C4: discs touch outside; C2/C3: one disc inside the other; maximum: least separation; magnitude: fraction of the Sun's diameter covered; obscuration: fraction of its area",
        "lunar": "Earth's shadow enlarged by Danjon's method (Skyfield eclipselib, as the event calendar); P1/P4 penumbra, U1/U4 umbra, U2/U3 total phase: the same instants everywhere; the place gives the Moon's altitude at each contact",
        "local_type": "solar: total, annular or partial when the Moon's disc reaches the Sun's as seen from the place, none otherwise; this geometry does not check the horizon: see visible",
        "visible": "the body's upper limb above the horizon (apparent altitude > -0.8333 deg with standard refraction) at one of the contacts or at maximum",
        "times": "UTC and local time, to the second"
      }
    },
    "eclipses": [
      {
        "kind": "solar",
        "global_type": "total",
        "greatest_eclipse_utc": "2024-04-08T18:17Z",
        "key": "eclipse:solar:total:2024-04-08T18:17Z",
        "local_type": "total",
        "magnitude": 1.0149,
        "obscuration": 1.0,
        "contacts": [
          {
            "utc": "2024-04-08T17:23:18Z",
            "local": "2024-04-08T12:23:18-05:00",
            "timestamp": 1712596998,
            "contact": "C1",
            "sun_altitude": 60.58,
            "sun_azimuth": 145.32,
            "sun_above_horizon": true
          },
          {
            "utc": "2024-04-08T18:40:43Z",
            "local": "2024-04-08T13:40:43-05:00",
            "timestamp": 1712601643,
            "contact": "C2",
            "sun_altitude": 64.68,
            "sun_azimuth": 186.91,
            "sun_above_horizon": true
          },
          {
            "utc": "2024-04-08T18:42:39Z",
            "local": "2024-04-08T13:42:39-05:00",
            "timestamp": 1712601759,
            "contact": "MAX",
            "sun_altitude": 64.62,
            "sun_azimuth": 188.02,
            "sun_above_horizon": true
          }
        ],
        "visible": true,
        "duration_minutes": 159.39,
        "central_duration_seconds": 231.3
      }
    ],
    "counts": {
      "eclipses": 1,
      "visible": 1
    }
  },
  "meta": {
    "engine": "astro-agents/1.9.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": "7cf94c46555fac0a5822ea4accedc536ea4beeb7d314c7b496eb5740a6e80469",
    "result_sha256": "b5912568c815c23d885ee764fb2f2bd37d29c87e47af3af2333a931ad3858f07",
    "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.subjectobjectThe place and its time zone.
result.settingsobjectstart, end, kinds and every convention (discs, contacts, magnitude, visibility).
result.eclipsesarrayOne row per eclipse: kind, global_type, greatest_eclipse_utc, key, visible, and local_type (solar), magnitude, obscuration, umbral/penumbral magnitude (lunar), contacts [{contact, utc, local, timestamp, and the Sun's or Moon's altitude, azimuth, above_horizon}], durations and visible.
result.countsobjecteclipses, and visible: those with the Sun or Moon above the horizon at a contact or at maximum.
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/eclipse-local?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.