/v1/festivals/vrat

Year-wise Vrat & Upavas lists by type — every Ekadashi (smarta + Vaishnava, with parana), Pradosh, Sankashti, Vinayaka, Purnima, Amavasya, Chandra Darshana, Masik Shivaratri, Durgashtami, Kalashtami, Skanda Shashthi, Masik Karthigai, Shraddha (all 16 Pitru Paksha tithis), Janmashtami (Smarta/ISKCON), Sankranti, Satyanarayana Puja or eclipse of a year at a location.

What this tells you

Year-wise vrat and upavas lists, one call per family per year: Ekadashi dates (smarta, plus Vaishnava and Gauna days when they differ), Pradosh, Sankashti, Vinayaka Chaturthi, Purnima, Amavasya, Shraddha dates, Janmashtami (Smarta and ISKCON), Masik Shivaratri, Durgashtami, Kalashtami, Skanda Shashthi, Karthigai, Satyanarayana Puja, Chandra Darshana, Bhanu Saptami, Sankranti and eclipses, for any year and any place. It uses the same location-aware engine as /v1/festivals/month and keeps only the entries whose `vrat_type` matches `type`.

`year` and `type` are required; an unknown type returns 400 with the valid list. 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/vrat?year=2027&type=ekadashi&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
`year`	yes	`2027`	Year (YYYY).
`type`	yes	`ekadashi`
`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

{
  "year": 2027,
  "type": "ekadashi",
  "ayanamsa": "lahiri",
  "location": {
    "lat": 28.6139,
    "lon": 77.209,
    "tz": "Asia/Kolkata",
    "month_system": "purnimanta"
  },
  "count": 30,
  "dates": [
    {
      "date": "2027-01-03",
      "name": "Saphala Ekadashi",
      "name_en": "Saphala Ekadashi",
      "name_hi": "सफला एकादशी",
      "type": "vrat",
      "importance": "major",
      "tithi": "Ekadashi",
      "paksha": "Krishna",
      "tithi_index": 26,
      "hindu_month": "Pausha",
      "hindu_month_purnimanta": "Pausha",
      "hindu_month_amanta": "Margashirsha",
      "vrat_type": "ekadashi",
      "observance": "sunrise",
      "windows": [
        {
          "label": "tithi",
          "start": "14:25",
          "end": "16:09"
        },
        {
          "label": "parana",
          "start": "07:14",
          "end": "10:42"
        }
      ],
      "note": "smarta and vaishnava on the same day"
    },
    {
      "date": "2027-01-18",
      "name": "Pausha Putrada Ekadashi",
      "name_en": "Pausha Putrada Ekadashi",
      "name_hi": "पौष पुत्रदा एकादशी",
      "type": "vrat",
      "importance": "major",
      "tithi": "Ekadashi",
      "paksha": "Shukla",
      "tithi_index": 11,
      "hindu_month": "Pausha",
      "hindu_month_purnimanta": "Pausha",
      "hindu_month_amanta": "Pausha",
      "vrat_type": "ekadashi",
      "observance": "sunrise",
      "windows": [
        {
          "label": "tithi",
          "start": "10:28",
          "end": "07:50"
        },
        {
          "label": "parana",
          "start": "14:18",
          "end": "17:50"
        }
      ],
      "note": "smarta"
    }
  ]
}

Field reference

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

Field	Type	Meaning
year	integer	Gregorian year, echoed (1800–2200). example: `2027`
type	string	The `type` parameter, echoed in lower case. One family or a comma-separated list: ekadashi, parana, pradosh, sankashti, vinayaka, purnima, amavasya, chandra_darshana, masik_shivaratri, durgashtami, kalashtami, skanda_shashthi, karthigai, shraddha, janmashtami, sankranti, satyanarayana, bhanu_saptami, eclipse. example: `"ekadashi"`
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"}`
count	integer	Number of items in `dates` (the full list; this sample shows 2). example: `30`
dates[]	array	Every occurrence of the requested families in the Gregorian year, in date order. Same objects as /v1/festivals/month. example: `[…]`
dates[].date	string (YYYY-MM-DD)	Civil date on which it is observed at the given location, already resolved with the rule's key moment (udaya, pradosh, nishita, moonrise, aparahna …), kshaya and vriddhi tithis, and Bhadra for Raksha Bandhan. example: `"2027-01-03"`
dates[].name	string	Name in the requested `locale`: en (default), hi, or the regional mr, ta, kn, bn, gu, pa. A regional locale falls back to the Hindi name when there is no regional one. example: `"Saphala Ekadashi"`
dates[].name_en	string	Canonical English name. Use it as a stable key. example: `"Saphala Ekadashi"`
dates[].name_hi	string	Hindi name in Devanagari. example: `"सफला एकादशी"`
dates[].type	string	tithi, vrat, sankranti, solar, nakshatra, jayanti, national or eclipse. example: `"vrat"`
dates[].importance	string	major, regional or minor. Use for UI prominence and filtering. example: `"major"`
dates[].tithi	string	The tithi tied to this observance. Absent (with `paksha` and `tithi_index`) for Gregorian-date entries (national days, fixed-date jayantis), Sankrantis and solar-calendar days. example: `"Ekadashi"`
dates[].paksha	string	"Shukla" or "Krishna". example: `"Krishna"`
dates[].tithi_index	integer (1–30)	1 = Shukla Pratipada … 15 = Purnima, 16 = Krishna Pratipada … 30 = Amavasya. example: `26`
dates[].hindu_month	string	Lunar month in the requested `month_system` (purnimanta by default). Prefixed "Adhik " in an adhik month. Absent for Gregorian-date entries. example: `"Pausha"`
dates[].hindu_month_purnimanta	string	Month name in the purnimanta system (North India). example: `"Pausha"`
dates[].hindu_month_amanta	string	Month name in the amanta system (South, West and East India). Differs from the purnimanta name in Krishna paksha. example: `"Margashirsha"`
dates[].vrat_type	string	Recurring-observance family: ekadashi, parana, pradosh, sankashti, vinayaka, purnima, amavasya, chandra_darshana, masik_shivaratri, durgashtami, kalashtami, skanda_shashthi, karthigai, shraddha, janmashtami, sankranti, satyanarayana, bhanu_saptami or eclipse. The same key /v1/festivals/vrat filters on. Absent for one-off festivals. example: `"ekadashi"`
dates[].observance	string	The moment of the day the rule was checked at: sunrise (default), arunodaya, purvahna, madhyahna, aparahna, sunset, pradosh, pradosh_overlap (the day whose pradosh kaal the tithi overlaps most), nishita or moonrise. A few rules return a rule-specific key such as aparahna_window, purvahna_end or frac:1.25 (a fitted fraction of the day or night). example: `"sunrise"`
dates[].windows[]	array	Local-time windows a calendar prints for this entry. Absent when there are none. example: `[{"label": "tithi", "start": "14:25", "end": "16:09"}, …]`
dates[].windows[].label	string	What the window is, e.g. tithi, nakshatra, pradosh_kaal, nishita_kaal, madhyahna, aparahna, moonrise, parana, bhadra, darshana, sankranti_moment, peak (eclipse). example: `"tithi"`
dates[].windows[].start	string (HH:MM)	Window start, local time in the request tz. No date. example: `"14:25"`
dates[].windows[].end	string (HH:MM)	Window end, local time. Absent for single moments (moonrise, sankranti_moment, peak). example: `"16:09"`
dates[].note	string	Extra marker: "smarta", "vaishnava", "smarta and vaishnava on the same day", "gauna (secondary) ekadashi", the parana instruction, or eclipse visibility at the place. example: `"smarta and vaishnava on the same day"`

Usage tips

How to use it

Ekadashi page
`type=ekadashi` gives smarta dates plus the separate Vaishnava/Gauna day when they differ. Read the `parana` window on each Ekadashi, or add `type=ekadashi,parana` to also get the Dwadashi parana days as separate entries.
Shraddha calendar
`type=shraddha` returns the Pitru Paksha days (Purnima to Sarva Pitru Amavasya) plus Bharani, Matri Navami and Magha Shraddha, with the aparahna window.
Cache per year, type and location
The list does not change; cache it for the year.

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.