Eclipses

GET`/api/eclipses`Pro

Compute exact solar and lunar eclipse moments over a date range using Swiss Ephemeris. Returns each eclipse's UTC datetime (minute precision), type (total / partial / annular / penumbral), and visibility, sorted chronologically.

What it returns

The endpoint scans a date range and returns every solar and lunar eclipse in it, in chronological order. Each eclipse carries the exact moment of maximum as a UTC ISO timestamp (minute precision), the type of eclipse, and visibility flags. You can restrict the scan to only solar or only lunar eclipses.

Eclipse moments are computed with Swiss Ephemeris — swe_sol_eclipse_when_glob for solar and swe_lun_eclipse_when for lunar — so they match the figures used by astronomical almanacs.

Request

Parameters

Parameter	Type	Required	Description
`startDate`	string	Yes	Start date in YYYY-MM-DD format
`endDate`	string	Yes	End date in YYYY-MM-DD format. Must be after startDate. Max range 3650 days (10 years).
`solarOnly`	string	No	Pass "true" to return only solar eclipses.
`lunarOnly`	string	No	Pass "true" to return only lunar eclipses.

Solar vs. lunar filter

Leave both filters off to get every eclipse. Set solarOnly=true for solar eclipses only, or lunarOnly=true for lunar eclipses only. Setting both at once is not meaningful — pick one.

thd-api

Response

A successful call returns { success, meta, data }. The meta block echoes the range and reports eclipseCount. The data array holds the eclipses, sorted by datetime.

Response200

{
"success": true,
"meta": {
  "version": "1.0.0",
  "timestamp": "2026-06-23T10:30:00.000Z",
  "endpoint": "eclipses",
  "startDate": "2026-01-01",
  "endDate": "2026-12-31",
  "eclipseCount": 4,
  "granularity": "minute",
  "swisseph": true
},
"data": [
  {
    "datetime": "2026-02-17T12:12:00.000Z",
    "type": "annular",
    "flag": 8,
    "visibility": ["central"],
    "kind": "global",
    "body": "Sun",
    "eclipse_class": "solar"
  },
  {
    "datetime": "2026-03-03T11:34:00.000Z",
    "type": "total",
    "flag": 4,
    "visibility": [],
    "kind": "global",
    "body": "Moon",
    "eclipse_class": "lunar"
  },
  {
    "datetime": "2026-08-12T17:46:00.000Z",
    "type": "total",
    "flag": 4,
    "visibility": ["central"],
    "kind": "global",
    "body": "Sun",
    "eclipse_class": "solar"
  },
  {
    "datetime": "2026-08-28T04:13:00.000Z",
    "type": "partial",
    "flag": 1,
    "visibility": [],
    "kind": "global",
    "body": "Moon",
    "eclipse_class": "lunar"
  }
]
}

Eclipse fields

Field	Description
`datetime`	UTC ISO timestamp of maximum eclipse, minute precision
`type`	`total`, `partial`, `annular`, `annular-total`, `penumbral`, or `noncentral`
`eclipse_class`	`solar` or `lunar`
`body`	`Sun` (solar eclipse) or `Moon` (lunar eclipse)
`kind`	`global` — the eclipse is computed for the whole Earth, not a single location
`visibility`	Array of contact flags (e.g. `central`, `first_contact`, `total_contact`, `penumbral`)
`flag`	Raw Swiss Ephemeris result bitmask behind `type` and `visibility`

Meta fields

Field	Description
`startDate` / `endDate`	The requested range, echoed back
`eclipseCount`	Number of eclipses returned
`granularity`	Always `minute` — timestamps are rounded to the minute
`swisseph`	`true` — confirms the figures come from Swiss Ephemeris

MCP tool: `get_eclipses`

The same calculation is available over the MCP server as the get_eclipses tool. It takes startDate, endDate, and the optional solarOnly / lunarOnly booleans, costs the same 1 Chart request, and returns the eclipses as a JSON string in result.content[0].text.

MCP result shape

Over MCP the filters solarOnly / lunarOnly are real booleans (not the string "true"). The result wraps the array as { "count": <n>, "data": [ /* same eclipse objects as above */ ] }.

tools/calljson

{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
  "name": "get_eclipses",
  "arguments": {
    "startDate": "2026-01-01",
    "endDate": "2026-12-31",
    "solarOnly": true
  }
}
}

Chart requests

1 Chart request per call (flat rate).

Constraint	Value
Required params	`startDate`, `endDate` (missing either returns `400`)
Date order	`endDate` must be after `startDate` (`400` otherwise)
Max range	3650 days (10 years)
Required tier	`advanced_chart`
Cost	1 Chart request per call