Solar and lunar eclipse API
Give a place and a date range (up to a year per call); get every solar and lunar eclipse with its local circumstances: whether and how it is seen from there, magnitude and obscuration, each contact time in local time with the Sun's altitude and azimuth, and the duration.
Get a free key Try it in the playground API reference
What you get
- Local type (total, annular, partial, none) and visibility from the place
- Magnitude and obscuration of the Sun
- Contacts C1 to C4 and the maximum, in local time, with the Sun's altitude and azimuth
- Global eclipse list with type and time of greatest eclipse (events route)
Example
curl -X POST https://astro-agent.dev/v1/astronomy/eclipse-local -H 'Content-Type: application/json' \
-H "X-Credits-Token: $ASTRO_AGENTS_KEY" -d '{"start":"2026-01-01","end":"2026-12-31","latitude":40.4168,"longitude":-3.7038}'
A real answer to this request (excerpt). The same request always returns the same
result_sha256, which POST https://astro-agent.dev/v1/verify recomputes for free:
{
"endpoint": "astronomy/eclipse-local",
"result": {
"counts": {
"eclipses": 4,
"visible": 2
},
"eclipses": [
{
"kind": "solar",
"global_type": "total",
"local_type": "partial",
"magnitude": 0.9987,
"obscuration": 0.9996,
"duration_minutes": 107.75,
"contacts": [
{
"C1": "2026-08-12T19:36:46+02:00"
},
{
"MAX": "2026-08-12T20:32:24+02:00"
},
{
"C4": "2026-08-12T21:24:31+02:00"
}
]
}
]
},
"meta": {
"result_sha256": "b0dce3ce4c2ea7664dd660ff8bc0b58acb72d49d251e946489a6ba8f2a66a2a0"
}
}
Routes and prices
| Route | Name | Price per call | What it returns |
|---|---|---|---|
POST /v1/astronomy/eclipse-local | Local circumstances of solar and lunar eclipses | $0.10 | 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 /v1/astronomy/events | Celestial event calendar (eclipses, stations, lunations) | $0.25 | Solar and lunar eclipses, planetary stations, lunations, separations, longitude crossings and declination events between two dates (1800-2200), to the minute. |
The same routes are MCP tools on https://astro-agent.dev/mcp.
Limits
- Dates from 1800 to 2200; range routes take up to a year per call.
- Without a key: 1 free call on the $0.01-0.02 routes, then HTTP 402 with a pay-per-call offer (USDC, x402).
- Free key (an email, no card): 10,000 calls a month, 30 a minute, personal, research and evaluation use only. Paid plans from $19 a month by card, for commercial use: see pricing.
- Past the quota, calls answer 429 until the 1st of the month: nothing is charged beyond the plan.
Alternatives
The US Naval Observatory API is free, but its local circumstances cover 2017 through 2024 only (its list of eclipses by year covers 1800-2050). Astro Agents computes local circumstances for any place from 1800 to 2200.
Checked on the providers' own pages on 2026-11-20. Their terms may have changed since.
When Astro Agents fits
- Eclipse planners, travel and astronomy apps that need local times for upcoming eclipses
- Historical research on eclipses seen from a given place
- The 2026 and 2027 eclipses over Europe and North Africa