Eclipse Detection in Natal Charts

What is the Eclipse endpoint?

You need to know which solar and lunar eclipses fall around a given birth date. The Eclipse endpoint takes birth data and returns those eclipses, each with the type (Solar or Lunar), the variant (Total Solar, Annular, Penumbral Lunar, etc.), the exact local datetime, and an orb showing how close the eclipse falls to the natal Sun or Moon.

This endpoint is part of the Natal Chart API.

Why does this endpoint exist?

You are building pre-natal eclipse features or eclipse-season content tied to a birth chart. In modern astrology, the closest eclipses to a birth are considered formative, and a natal Sun or Moon's proximity to an eclipse degree is a meaningful interpretive signature. Detecting which eclipses fall near a birth, classifying them, and computing the orb takes specialized work. This endpoint runs it in one call.

What inputs does it need?

You pass standard birth data: API key, full name, date components, time components, gender, place, decimal latitude and longitude, and timezone offset from UTC. The endpoint scopes its eclipse search around the birth date and returns timestamps in your local timezone. Authentication uses a Bearer token in the Authorization header.

What does the response data look like?

You get an envelope with status, code, message, and data. The data object reports an eclipse_count and an eclipse_data array. Each entry in the array describes one eclipse: its type, variant, exact local datetime, and the orb to a related natal point.

Solar eclipses surface relative to the natal Sun; lunar eclipses to the natal Moon. Tighter orbs (under 5 degrees) indicate eclipses interpreted as more formative.

What does a real response look like?

Below is the response for a sample birth (24 May 2023, 14:40:43 IST, New Delhi). The endpoint returns four eclipses across the 2023 eclipse seasons: two solar and two lunar.

{
  "status": "success",
  "code": 200,
  "message": "Request successful",
  "data": {
    "eclipse_count": 4,
    "eclipse_data": [
      {
        "eclipse": "Solar",
        "eclipse_type": "Total Solar",
        "datetime": "2023-04-20 09:42:00",
        "orb": 4.59
      },
      {
        "eclipse": "Lunar",
        "eclipse_type": "Penumbral Lunar",
        "datetime": "2023-05-05 23:04:00",
        "orb": 11.37
      },
      {
        "eclipse": "Solar",
        "eclipse_type": "Total Solar",
        "datetime": "2023-10-14 23:25:00",
        "orb": 3.9
      },
      {
        "eclipse": "Lunar",
        "eclipse_type": "Penumbral Lunar",
        "datetime": "2023-10-29 01:54:00",
        "orb": 10.88
      }
    ]
  }
}

What can you build with this endpoint?

You use Eclipse data whenever your product surfaces eclipse-related content tied to a birth chart. The structured response works for both visual timelines and per-eclipse interpretation panels, and the orb field lets you filter to only the closest, most-formative eclipses for that specific birth.

1. Pre-natal eclipse highlights. Surface the closest solar or lunar eclipse before the birth date as the "pre-natal eclipse," a widely-cited modern astrology feature.
2. Eclipse-orb interpretation. Sort by orb ascending and surface tight-orb eclipses (under 5 degrees) as formative chart signatures with dedicated reading content.
3. Eclipse timeline UI. Render the 4-eclipse year as a visual timeline with type icons, helping users see the eclipse season pattern around their birth.
4. Saros-cycle features. Eclipses repeat in Saros cycles (about 18 years). Combine this endpoint's results across multiple birth dates to surface family or generational eclipse patterns.

How accurate is the calculation?

You are computing eclipse times and types, both of which Swiss Ephemeris with NASA JPL ephemeris data handles with high precision. Eclipse datetimes are accurate to the minute, and type classification (Total, Annular, Partial, Penumbral) follows standard astronomical definitions.

The orb value depends on which natal point each eclipse is measured against (Sun for solar eclipses, Moon for lunar). The endpoint returns orbs as raw degrees, so you can apply your own threshold for "close enough to matter" interpretation logic.

How does this relate to the parent API?

You are layering eclipse-aware content on top of the standard birth chart. This endpoint complements the Natal Chart API by surfacing the eclipses around a birth datetime, a feature the position-focused endpoints do not provide.

Planetary Positions returns the natal Sun and Moon positions; this endpoint surfaces the eclipses that fall near them. Combine the two when your UI needs to highlight tight-orb eclipses as natal signatures, or when you want to render eclipse content alongside the standard chart.

Summary

The Eclipse endpoint returns the solar and lunar eclipses that fall around a given birth date, each classified by type and variant, timestamped to the minute in local time, and reported with the orb to the related natal point. It runs on Swiss Ephemeris with NASA JPL ephemeris data. Use it for pre-natal eclipse features, eclipse-season content engines, eclipse-orb interpretation, and any UI that ties eclipses to natal placements.