Compute Festivals
Compute Hindu festival dates for a year and location. The ``calendar_system`` parameter affects Krishna Paksha festival dates. Shukla Paksha festivals are identical in both Purnimant and Amant systems. Each festival is enriched with shastric metadata from lilavati's curated set when available — shloka, presiding deity, kathā summary, Kadambini verse refs. Festivals without a metadata entry return ``metadata: null`` and the caller falls back gracefully.
GET /lilavati/v1/festivals
Compute Hindu festival dates for a year and location.
The calendar_system parameter affects Krishna Paksha festival dates.
Shukla Paksha festivals are identical in both Purnimant and Amant systems.
Each festival is enriched with shastric metadata from lilavati's
curated set when available — shloka, presiding deity, kathā summary,
Kadambini verse refs. Festivals without a metadata entry return
metadata: null and the caller falls back gracefully.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
year | integer | No | Year. Defaults to current year. |
calendar_system | string | No | Lunar calendar system: purnimant (North India) or amant (South/West). Default: purnimant |
lat | number | Yes | Latitude |
lng | number | Yes | Longitude |
tz | string | No | IANA timezone (e.g. 'Asia/Kolkata') Default: Asia/Kolkata |
altitude | number | No | Altitude in meters Default: 0 |
Response
Returns an array of EnrichedFestivalInfo objects.
| Field | Type | Description |
|---|---|---|
id | string | Festival identifier (e.g. 'diwali') |
name | string | Festival display name |
date | string | Festival date |
sunrise | `string | null` (optional) |
tithi_at_sunrise | integer | Tithi number at sunrise |
lunar_month | string | Lunar month name |
is_adhik_month | boolean (optional) | Whether in Adhik month |
reasoning | string | Explanation of date determination |
priority_applied | string (optional) | Observance rule applied — one of: paraviddha, puurvaviddha, vyapti, sankranti, nakshatra_at_sunrise. |
kaala_applied | string (optional) | Kaala (time-window) checked for vyapti resolution; empty when not applicable |
alternate | `AlternateObservance | null` (optional) |
metadata | `FestivalMetadata | null` (optional) |