/v1/festivals/month

Full Hindu festival calendar for a month at a location: every named Ekadashi (smarta + Vaishnava/Gauna, with parana window), Pradosh by weekday, Sankashti/Vinayaka Chaturthi, every Purnima and Amavasya (Somavati, Darsha, Anvadhan, Ishti), Chandra Darshana, all 12 Sankrantis, major + regional festivals, lunar and fixed-date jayantis, national days, eclipses. verified entry for entry against the printed panchang calendars of 14 cities.

What this tells you

The complete Hindu calendar for a Gregorian month at a location, the same list a printed panchang shows: every named Ekadashi (smarta, plus the Vaishnava and Gauna days when they differ, each with a parana window), Pradosh Vrat named by weekday, Sankashti and Vinayaka Chaturthi with their monthly names, every Purnima and Amavasya named by month (Somavati, Shani, Darsha, Anvadhan, Ishti), Chandra Darshana, Masik Shivaratri, Durgashtami, Kalashtami, Skanda Shashthi, all 12 Sankrantis, the major festivals, regional observances of Tamil Nadu, Kerala, Maharashtra, Telugu and Kannada states, Bengal, Odisha, Assam, Gujarat and Punjab, lunar and fixed-date jayantis, national days, and solar and lunar eclipses. Dates are location-aware: sunrise, moonrise and pradosh kaal are computed for the given lat/lon and timezone, so Karwa Chauth, Sankashti, Pradosh or an Ekadashi can fall on different days in Delhi, London and Toronto. The engine is tested against the 2027 printed panchang calendars of 14 cities (Delhi, Chennai, Bengaluru, Hyderabad, Pune, Dubai, Singapore, London, Melbourne, Sydney, San Francisco, Seattle, Toronto, Brampton).

`year` and `month` are 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/month?year=2027&month=10&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).
`month`	yes	`10`	Month number (1–12).
`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,
  "month": 10,
  "ayanamsa": "lahiri",
  "location": {
    "lat": 28.6139,
    "lon": 77.209,
    "tz": "Asia/Kolkata",
    "month_system": "purnimanta"
  },
  "festivals": [
    {
      "date": "2027-10-01",
      "name": "Chandra Darshana",
      "name_en": "Chandra Darshana",
      "name_hi": "चन्द्र दर्शन",
      "type": "tithi",
      "importance": "minor",
      "tithi": "Dwitiya",
      "paksha": "Shukla",
      "tithi_index": 2,
      "hindu_month": "Ashwin",
      "hindu_month_purnimanta": "Ashwin",
      "hindu_month_amanta": "Ashwin",
      "vrat_type": "chandra_darshana",
      "observance": "sunset",
      "windows": [
        {
          "label": "darshana",
          "start": "18:08",
          "end": "18:41"
        }
      ]
    },
    {
      "date": "2027-10-02",
      "name": "Gandhi Jayanti",
      "name_en": "Gandhi Jayanti",
      "name_hi": "गांधी जयन्ती",
      "type": "jayanti",
      "importance": "major",
      "observance": "sunrise"
    }
  ]
}

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`
month	integer (1–12)	Gregorian month, echoed. example: `10`
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	Every occurrence in the Gregorian month, ordered by date, then major → regional → minor. Empty array when there are none. example: `[…]`
festivals[].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-10-01"`
festivals[].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: `"Chandra Darshana"`
festivals[].name_en	string	Canonical English name. Use it as a stable key. example: `"Chandra Darshana"`
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. Use for UI prominence and filtering. example: `"minor"`
festivals[].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: `"Dwitiya"`
festivals[].paksha	string	"Shukla" or "Krishna". example: `"Shukla"`
festivals[].tithi_index	integer (1–30)	1 = Shukla Pratipada … 15 = Purnima, 16 = Krishna Pratipada … 30 = Amavasya. example: `2`
festivals[].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: `"Ashwin"`
festivals[].hindu_month_purnimanta	string	Month name in the purnimanta system (North India). example: `"Ashwin"`
festivals[].hindu_month_amanta	string	Month name in the amanta system (South, West and East India). Differs from the purnimanta name in Krishna paksha. example: `"Ashwin"`
festivals[].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: `"chandra_darshana"`
festivals[].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: `"sunset"`
festivals[].windows[]	array	Local-time windows a calendar prints for this entry. Absent when there are none. example: `[{"label": "nakshatra", "start": "15:21", "end": "16:18"}, …]`
festivals[].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: `"darshana"`
festivals[].windows[].start	string (HH:MM)	Window start, local time in the request tz. No date. example: `"18:08"`
festivals[].windows[].end	string (HH:MM)	Window end, local time. Absent for single moments (moonrise, sankranti_moment, peak). example: `"18:41"`

Usage tips

How to use it

Filter by importance and type
For a compact UI show `importance = "major"`. Filter `type = "vrat"` for a fasting calendar, `type = "sankranti"` for solar dates, `type = "eclipse"` for grahan.
Always pass the user's location
Without lat/lon/tz the dates are for New Delhi. Users in London or Toronto get different Ekadashi and Sankashti dates: pass their coordinates and IANA timezone.
South and West India
Pass `month_system=amanta` for Marathi, Gujarati, Kannada, Telugu and Tamil calendars so `hindu_month` and "<Month> Amavasya" labels follow their convention. Dates do not change.
Hindi and regional names
`locale=hi` returns Devanagari names; mr, ta, kn, bn, gu and pa give regional names where they exist, falling back to Hindi. `name_en` and `name_hi` are returned in every case.
Cache per calendar month and location
The list for a city and month does not change. Cache it for a long time.

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.