/v1/festivals/on-date

All festivals, vrats and observances on one civil date at a location — same engine and fields as /v1/festivals/month.

What this tells you

Everything observed on one date at one place: festivals, vrats, Ekadashi (smarta and Vaishnava), Pradosh, Purnima and Amavasya, Sankranti, jayantis and eclipses, with the windows a panchang prints for each (moonrise for Karwa Chauth and Sankashti, pradosh kaal, parana). Built for "today's festivals" widgets and for annotating panchang cards. Uses the same engine as /v1/festivals/month.

`date` is required. Window times are "HH:MM" in the request tz with no date. A tithi or nakshatra window often starts on the previous day, so `start` can be later than `end` (e.g. a tithi window 20:49 → 19:07). The Ekadashi `parana` window is on the day after the Ekadashi. Some entries also carry `note` (for example "smarta", "vaishnava", "smarta and vaishnava on the same day", or eclipse visibility at the place) and `is_adhik_maas: true` inside an adhik month.

Request

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

example request

curl "https://api.lifeastroapi.com/v1/festivals/on-date?date=2027-10-29&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
`date`	yes	`2027-10-29`	Date (YYYY-MM-DD).
`lat`	no	`28.6139`	Latitude in decimal degrees.
`lon`	no	`77.209`	Longitude in decimal degrees.
`locale`	no	—	Language for the `name` field: en (default), hi, mr, ta, kn, bn, gu, pa. `name_en` and `name_hi` are always present.
`month_system`	no	—	Lunar month convention for labels ("<Month> Amavasya"), the hindu_month field and month-membership vrats such as Shravan Somwar: purnimanta (default; North India) or amanta (South, West and East India). Festival dates never change with this option.
`ayanamsa`	no	—	Ayanamsa (sidereal offset) to use. Defaults to lahiri.

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

{
  "date": "2027-10-29",
  "ayanamsa": "lahiri",
  "location": {
    "lat": 28.6139,
    "lon": 77.209,
    "tz": "Asia/Kolkata",
    "month_system": "purnimanta"
  },
  "festivals": [
    {
      "date": "2027-10-29",
      "name": "Diwali",
      "name_en": "Diwali",
      "name_hi": "दीवाली",
      "type": "tithi",
      "importance": "major",
      "tithi": "Amavasya",
      "paksha": "Krishna",
      "tithi_index": 30,
      "hindu_month": "Kartik",
      "hindu_month_purnimanta": "Kartik",
      "hindu_month_amanta": "Ashwin",
      "observance": "pradosh_overlap",
      "windows": [
        {
          "label": "pradosh_kaal",
          "start": "17:39",
          "end": "19:15"
        },
        {
          "label": "tithi",
          "start": "20:49",
          "end": "19:07"
        }
      ]
    },
    {
      "date": "2027-10-29",
      "name": "Lakshmi Puja",
      "name_en": "Lakshmi Puja",
      "name_hi": "लक्ष्मी पूजा",
      "type": "tithi",
      "importance": "major",
      "tithi": "Amavasya",
      "paksha": "Krishna",
      "tithi_index": 30,
      "hindu_month": "Kartik",
      "hindu_month_purnimanta": "Kartik",
      "hindu_month_amanta": "Ashwin",
      "observance": "pradosh_overlap",
      "windows": [
        {
          "label": "pradosh_kaal",
          "start": "17:39",
          "end": "19:15"
        },
        {
          "label": "tithi",
          "start": "20:49",
          "end": "19:07"
        }
      ]
    }
  ]
}

Field reference

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

Field	Type	Meaning
date	string (YYYY-MM-DD)	Requested civil date, echoed (1800–2200). example: `"2027-10-29"`
ayanamsa	string	Ayanamsa used (default lahiri). example: `"lahiri"`
location	object	What the dates were computed for. Defaults: New Delhi (lat 28.6353, lon 77.225), tz Asia/Kolkata, month_system purnimanta. example: `{"lat": 28.6139, "lon": 77.209, "tz": "Asia/Kolkata", "month_system": "purnimanta"}`
festivals[]	array	Everything observed on this date at this place, ordered major → regional → minor. Same objects as /v1/festivals/month. Empty array when nothing is observed. example: `[…]`
festivals[].name	string	Name in the requested `locale` (en default; hi, mr, ta, kn, bn, gu, pa). example: `"Diwali"`
festivals[].name_en	string	Canonical English name. Use it as a stable key. example: `"Diwali"`
festivals[].name_hi	string	Hindi name in Devanagari. example: `"दीवाली"`
festivals[].type	string	tithi, vrat, sankranti, solar, nakshatra, jayanti, national or eclipse. example: `"tithi"`
festivals[].importance	string	major, regional or minor. example: `"major"`
festivals[].tithi	string	The tithi tied to this observance. example: `"Amavasya"`
festivals[].tithi_index	integer (1–30)	1 = Shukla Pratipada … 15 = Purnima, 16 = Krishna Pratipada … 30 = Amavasya. example: `30`
festivals[].hindu_month	string	Lunar month in the requested `month_system` (purnimanta by default). `hindu_month_purnimanta` and `hindu_month_amanta` give both. example: `"Kartik"`
festivals[].observance	string	The moment of the day the rule was checked at, e.g. sunrise, pradosh, pradosh_overlap, nishita, moonrise, aparahna. See /v1/festivals/month. example: `"pradosh_overlap"`
festivals[].windows[]	array	Local-time windows ("HH:MM", no date) a panchang prints for the entry: tithi span, pradosh kaal, nishita kaal, moonrise, parana and so on. example: `[{"label": "pradosh_kaal", "start": "17:39", "end": "19:15"}, …]`

Usage tips

How to use it

Include in a daily panchang card
Call this in parallel with /v1/panchang/basic and render each `name` with its `windows` (e.g. "Diwali · pradosh kaal 17:39–19:15").
Regional lists
Filter `importance = "regional"` in or out depending on the audience; Tamil, Kerala, Marathi, Telugu, Bengali and Gujarati observances are included.
Pass the user's location
Without lat/lon/tz the date is evaluated for New Delhi. Moonrise-based vrats can move by a day for other places.

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.