/v1/eclipses/solar

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

What this tells you

Solar eclipses (surya 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.

Request

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

example request

curl "https://api.lifeastroapi.com/v1/eclipses/solar?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": "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": "solar",
      "type": "total",
      "peak_jd": 2461619.921312,
      "peak_utc": "2027-08-02T10:06:41Z",
      "nakshatra_index": 7,
      "nakshatra": "Pushya",
      "visible_from_india": true,
      "local": {
        "visible": true,
        "visibility_note": "visible from this location",
        "contacts": [
          {
            "phase": "sparsha",
            "jd": 2461619.93315,
            "local": "2027-08-02 15:53"
          },
          {
            "phase": "madhya",
            "jd": 2461619.957884,
            "local": "2027-08-02 16:29"
          }
        ],
        "obscuration": 0.082595,
        "magnitude": 0.168842,
        "sutak": {
          "applies": true,
          "start_local": "2027-08-02 03:53",
          "end_local": "2027-08-02 17:02",
          "note": "Surya grahan sutak begins 12 hours (4 prahar) before sparsha and ends at moksha"
        },
        "local_date": "2027-08-02"
      }
    }
  ]
}

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	total, annular, partial or hybrid. 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 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). 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. example: `[{"phase": "sparsha", "jd": 2461619.93315, "local": "2027-08-02 15:53"}, …]`
eclipses[].local.contacts[].phase	string	Phase name (see contacts[] above). example: `"sparsha"`
eclipses[].local.contacts[].jd	number	Julian Day (UT) of the phase. example: `2461619.93315`
eclipses[].local.contacts[].local	string (YYYY-MM-DD HH:MM)	Phase time in the request tz, seconds dropped. example: `"2027-08-02 15:53"`
eclipses[].local.magnitude	number	Only when visible: fraction of the Sun's diameter covered by the Moon at local maximum. example: `0.168842`
eclipses[].local.obscuration	number	Only when visible: fraction of the Sun's disc area covered at local maximum. example: `0.082595`
eclipses[].local.sutak.applies	boolean	Whether sutak is observed at this place. False where the eclipse is not visible. example: `false`
eclipses[].local.sutak.start_local	string (YYYY-MM-DD HH:MM)	Sutak start in the request tz: 12 hours (4 prahar) before sparsha. Only present when `applies` is true. example: `"2027-08-02 03:53"`
eclipses[].local.sutak.end_local	string (YYYY-MM-DD HH:MM)	Sutak end: moksha. Only present when `applies` is true. example: `"2027-08-02 17:02"`
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 of sparsha at this place; for an 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.