/v1/eclipses/all

All solar and lunar eclipses in a date range (grahan list) — with lat/lon the local contact times, visibility and sutak kaal, as a printed panchang shows.

What this tells you

All solar and lunar eclipses between start_date and end_date, merged and sorted by peak: the grahan list of a panchang. 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). A visible solar eclipse also gets `local.magnitude` and `local.obscuration` (fraction of the Sun's diameter and disc area covered at local maximum).

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.

Request

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

example request

curl "https://api.lifeastroapi.com/v1/eclipses/all?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.
`start_year`	no	—
`end_year`	no	—

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": "solar",
      "type": "annular",
      "peak_jd": 2461443.166422,
      "peak_utc": "2027-02-06T15:59:38Z",
      "nakshatra_index": 22,
      "nakshatra": "Dhanishta",
      "visible_from_india": false,
      "local": {
        "visible": false,
        "visibility_note": "not visible from this location",
        "contacts": null,
        "sutak": {
          "applies": false,
          "note": "Sutak is observed only where the eclipse is visible"
        },
        "local_date": "2027-02-06"
      }
    },
    {
      "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"
      }
    }
  ]
}

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: `"solar"`
eclipses[].type	string	Solar: total, annular, partial or hybrid. Lunar: total, partial or penumbral (upachchaya). example: `"annular"`
eclipses[].peak_jd	number	Julian Day (UT) of greatest eclipse (global, not for your location). example: `2461443.166422`
eclipses[].peak_utc	string (ISO 8601, UTC)	Same moment as peak_jd in UTC. example: `"2027-02-06T15:59:38Z"`
eclipses[].nakshatra_index	integer (0–26)	Sidereal nakshatra of the Sun (solar) or Moon (lunar) at the peak, using the requested `ayanamsa`. 0 = Ashwini. example: `22`
eclipses[].nakshatra	string	Name of that nakshatra. example: `"Dhanishta"` 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: `false`
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	Solar: the eclipse is seen from the place (Sun above the horizon during the local eclipse). Lunar: the Moon is above the horizon at some point between the first and last umbral contact (penumbral contacts for a penumbral eclipse). example: `false`
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: `"not visible from this location"`
eclipses[].local.contacts[]	array or null	Phase moments in time order. Solar phases: sparsha (first contact), sammilana (totality or annularity begins), madhya (maximum), unmilana (totality or annularity ends), moksha (last contact). Phases that do not happen at the place are left out. `null` when a solar eclipse is not visible from the place. 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 eclipse is not visible, and for a penumbral lunar eclipse. When true, the object also has `start_local` (12 hours before sparsha for a solar eclipse, 9 hours for a lunar one) 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: `"Sutak is observed only where the eclipse is visible"`
eclipses[].local.local_date	string (YYYY-MM-DD)	Civil date in the request tz on which the eclipse begins at this place: sparsha (lunar: first umbral contact, or penumbral_begin when there is no umbral phase). For a solar eclipse not visible here, the date of the global peak. example: `"2027-02-06"`

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.