/v1/eclipses/lunar

Lunar eclipses in a date range — type, peak, nakshatra; with lat/lon the local contact times, visibility and sutak kaal.

What this tells you

Lunar eclipses (chandra grahan) between start_date and end_date. Without lat/lon you get the global list: type, peak, nakshatra and a rough India flag. With lat/lon (and tz) every eclipse also carries a `local` block: contact times (sparsha, madhya, moksha …) in local time, whether it is visible there, and the sutak period with the classical rule applied (12 hours before sparsha for surya grahan, 9 hours for chandra grahan, none for a penumbral eclipse or where the eclipse is not visible).

The search covers whole UT days, from 00:00 UT on `start_date` to the end of `end_date`. `start_date` must be before `end_date` and the span can be at most 5 years. An eclipse is listed by its UT peak, so filter on `local.local_date` when you need the local calendar date. When lat/lon are passed without tz, local times use Asia/Kolkata. Lunar eclipses have no `magnitude` or `obscuration` in the local block.

Request

All requests require an Authorization header with your dv_live_* API key.

example request

curl "https://api.lifeastroapi.com/v1/eclipses/lunar?start_date=2027-01-01&end_date=2027-12-31&lat=28.6139&lon=77.209" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query parameters

Checked against the API: a parameter is marked required when the request fails without it.

Name	Required	Example	Description
`start_date`	yes	`2027-01-01`	First date of the range (YYYY-MM-DD).
`end_date`	yes	`2027-12-31`	Last date of the range (YYYY-MM-DD).
`lat`	no	`28.6139`	Latitude in decimal degrees.
`lon`	no	`77.209`	Longitude in decimal degrees.

Response (200 OK)

The real response to the example request above, generated from the API itself. Long arrays are trimmed to their first two items. Field names are stable across versions.

200 response

{
  "start_date": "2027-01-01",
  "end_date": "2027-12-31",
  "location": {
    "lat": 28.6139,
    "lon": 77.209,
    "tz": "Asia/Kolkata",
    "month_system": ""
  },
  "eclipses": [
    {
      "kind": "lunar",
      "type": "penumbral",
      "peak_jd": 2461457.467278,
      "peak_utc": "2027-02-20T23:12:52Z",
      "nakshatra_index": 9,
      "nakshatra": "Magha",
      "visible_from_india": true,
      "local": {
        "visible": true,
        "visibility_note": "penumbral (upachchaya) eclipse — visible but no sutak is observed",
        "contacts": [
          {
            "phase": "penumbral_begin",
            "jd": 2461457.383596,
            "local": "2027-02-21 02:42"
          },
          {
            "phase": "madhya",
            "jd": 2461457.467278,
            "local": "2027-02-21 04:42"
          }
        ],
        "sutak": {
          "applies": false,
          "note": "No sutak for a penumbral (upachchaya) lunar eclipse"
        },
        "local_date": "2027-02-21"
      }
    },
    {
      "kind": "lunar",
      "type": "penumbral",
      "peak_jd": 2461605.168755,
      "peak_utc": "2027-07-18T16:03:00Z",
      "nakshatra_index": 20,
      "nakshatra": "Uttara Ashadha",
      "visible_from_india": true,
      "local": {
        "visible": true,
        "visibility_note": "penumbral (upachchaya) eclipse — visible but no sutak is observed",
        "contacts": [
          {
            "phase": "penumbral_begin",
            "jd": 2461605.164205,
            "local": "2027-07-18 21:26"
          },
          {
            "phase": "madhya",
            "jd": 2461605.168755,
            "local": "2027-07-18 21:33"
          }
        ],
        "sutak": {
          "applies": false,
          "note": "No sutak for a penumbral (upachchaya) lunar eclipse"
        },
        "local_date": "2027-07-18"
      }
    }
  ]
}

Field reference

Every field in the response, with its type, a real example, and what it means.

Field	Type	Meaning
start_date	string (YYYY-MM-DD)	Start of the requested range, echoed. example: `"2027-01-01"`
end_date	string (YYYY-MM-DD)	End of the requested range, echoed. example: `"2027-12-31"`
location	object	Present only when lat and lon are passed. `tz` defaults to Asia/Kolkata. `month_system` is always an empty string on this endpoint. example: `{"lat": 28.6139, "lon": 77.209, "tz": "Asia/Kolkata", "month_system": ""}`
eclipses[]	array	Eclipses in the range, ordered by peak. Empty array when there are none. example: `[…]`
eclipses[].kind	string	"solar" or "lunar". example: `"lunar"`
eclipses[].type	string	total, partial or penumbral (upachchaya). example: `"penumbral"`
eclipses[].peak_jd	number	Julian Day (UT) of greatest eclipse (global, not for your location). example: `2461457.467278`
eclipses[].peak_utc	string (ISO 8601, UTC)	Same moment as peak_jd in UTC. example: `"2027-02-20T23:12:52Z"`
eclipses[].nakshatra_index	integer (0–26)	Sidereal nakshatra of the Moon at the peak, using the requested `ayanamsa`. 0 = Ashwini. example: `9`
eclipses[].nakshatra	string	Name of that nakshatra. example: `"Magha"` Jyotish: Used for grahan phal by janma nakshatra: natives born in the eclipse nakshatra are traditionally advised extra care.
eclipses[].visible_from_india	boolean	Rough flag based only on the UTC time of the global peak: for a solar eclipse true when the peak falls between 01:00 and 13:30 UTC (daytime in India), for a lunar eclipse true when it falls between 13:30 and 01:00 UTC (night in India). It does not check the eclipse path. Use `local.visible` for a real answer at a place. example: `true`
eclipses[].local	object	Present only when lat and lon are passed: what a panchang prints for this eclipse at that place. example: `{ "visible": true, "sutak": { … } }`
eclipses[].local.visible	boolean	Lunar: the Moon is above the horizon at some point between the first and last umbral contact (penumbral contacts for a penumbral eclipse). example: `true`
eclipses[].local.visibility_note	string	Short reason, e.g. "visible from this location", "not visible from this location", "Moon below the horizon for the whole eclipse at this location", or the penumbral (upachchaya) note. example: `"penumbral (upachchaya) eclipse — visible but no sutak is observed"`
eclipses[].local.contacts[]	array	Phase moments in time order. Lunar phases: penumbral_begin, sparsha (umbral first contact), sammilana (totality begins), madhya (maximum), unmilana (totality ends), moksha (umbral last contact), penumbral_end. Phases the eclipse does not have are left out. Lunar contact times are the same instant everywhere; only the local clock time changes. example: `[{"phase": "penumbral_begin", "jd": 2461457.383596, "local": "2027-02-21 02:42"}, …]`
eclipses[].local.contacts[].phase	string	Phase name (see contacts[] above). example: `"penumbral_begin"`
eclipses[].local.contacts[].jd	number	Julian Day (UT) of the phase. example: `2461457.383596`
eclipses[].local.contacts[].local	string (YYYY-MM-DD HH:MM)	Phase time in the request tz, seconds dropped. example: `"2027-02-21 02:42"`
eclipses[].local.sutak.applies	boolean	Whether sutak is observed at this place. False where the Moon stays below the horizon, and for a penumbral eclipse. When true, the object also has `start_local` (9 hours, 3 prahar, before sparsha) and `end_local` (moksha), both "YYYY-MM-DD HH:MM" in the request tz. example: `false`
eclipses[].local.sutak.note	string	The rule applied, or why there is no sutak. Safe to show to users as is. example: `"No sutak for a penumbral (upachchaya) lunar eclipse"`
eclipses[].local.local_date	string (YYYY-MM-DD)	Civil date in the request tz of the first umbral contact (sparsha), or of penumbral_begin when there is no umbral phase. example: `"2027-02-21"`

Usage tips

How to use it

Grahan page for a city
Query the whole year with the city's lat, lon and tz. Show only eclipses where `local.visible` is true; print `contacts` and `sutak.start_local` – `sutak.end_local`.
Pregnancy / temple-closure notices
Sutak is what users ask for. Use `sutak.applies` and `sutak.note` verbatim; the note explains why an eclipse has no sutak.
Cache
Eclipse data for a given range does not change; cache per range and location.

Errors

Every error follows the same envelope. Use the error.code field (not the message) for conditional logic in your integration.

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

402 Payment Required

{
  "error": {
    "code": "trial_exhausted",
    "message": "your free trial credits are exhausted — pick a plan to continue",
    "top_up_url": "https://lifeastroapi.com/pricing",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded; retry after 12 seconds",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

Try it

Get a dv_live_* key from your dashboard and paste into the cURL snippet above. New accounts get 1,500 free credits. Sign up.