# Hindu calendar - festivals, vrats, lunar months, regional calendars, ICS

Six endpoints that turn the [panchang](/en/vedic/panchang/) into a calendar. Nothing is read from a table of dates: every festival is a rule (lunar month, tithi and the part of the day the rite belongs to, or a solar ingress), and the date is computed for the place you send. New York gets the days its own sunrise and sunset give, which in 2025 is a day earlier than New Delhi for 48 festivals.

Every entry returns the rule that dated it, its source and how the day was decided, so a disagreement with a printed almanac can be traced to the condition that caused it.

## Endpoints

| Endpoint | Credits | What it returns |
|---|---|---|
| `POST /v1/vedic/calendar/festivals` | 100 | About 55 festivals of the year, each with rule, source, tithi window and month |
| `POST /v1/vedic/calendar/vrats` | 100 | Ekadashi (Smarta and Vaishnava, with parana), Pradosh, Sankashti, Purnima, Amavasya, Masik Shivaratri |
| `POST /v1/vedic/calendar/months` | 50 | Lunar months with adhika and kshaya, sankrantis, Shaka and Vikram eras |
| `POST /v1/vedic/calendar/regional/months` | 50 | Month boundaries of a Tamil, Malayalam, Bengali, Gujarati or Marathi year |
| `POST /v1/vedic/calendar/regional/date` | 20 | One Gregorian date in a regional calendar |
| `GET /v1/vedic/calendar/ics` | 100 | The festivals and vrats of a year as an iCalendar file |

All of them take `latitude`, `longitude` and `timezone` (an IANA name such as `Asia/Kolkata`, or `auto`, the default, to look it up from the coordinates). The zone is applied day by day, so summer time abroad is followed. A fixed `timezoneOffset` is accepted instead. Latitudes beyond 66 degrees are refused: there the Sun does not rise on some days and a Hindu day, which runs from sunrise to sunrise, has no start. `ayanamsaId` (or `ayanamsa` by name) sets the sidereal zodiac for the sankrantis and month names; Lahiri is the default.

```bash
curl https://api.astroway.info/v1/vedic/calendar/festivals \
  -H "X-Api-Key: $ASTROWAY_KEY" -H "Content-Type: application/json" \
  -d '{ "year": 2026, "latitude": 28.6139, "longitude": 77.209, "timezone": "Asia/Kolkata", "festivals": ["diwali"] }'
```

## How a festival is dated

A lunar festival names a month, a tithi and a kala, the part of the day its rite belongs to. The tithi is kept on the day it is in force during that kala:

| Kala | Window |
|---|---|
| sunrise | the moment of sunrise (udaya tithi) |
| arunodaya | the 96 minutes (4 ghatis) before sunrise |
| pratahkala, madhyahna, aparahna, sayahna | the 1st, 3rd, 4th and 5th fifth of daylight |
| purvahna | the first half of daylight |
| pradosha | the first fifth of the night (three muhurtas after sunset) |
| purvaratri | the first half of the night |
| nishita | the eighth of the fifteen muhurtas of the night |
| moonrise | the moment of moonrise |

`basis` says how the day was decided: `vyapti` when the tithi met the kala on one day, `vriddhi` when it met it on two and the rule's tie-break chose (first, second, or the one it covered longer), `kshaya` when it met it on neither and the rule's fallback chose. Raksha Bandhan and Holika Dahan also exclude Bhadra (Vishti karana). Ganga Dussehra is kept in the adhika month when the year has Adhika Jyeshtha, as in 2026.

Solar festivals follow the regional rule of the calendar they belong to: Makar Sankranti and Thai Pongal on the day of the transit if it falls before sunset, Vishu at the first sunrise after the Mesha transit, Pohela Boishakh by the Bengali rule. Onam is the day Thiruvonam (Shravana) is in force at sunrise in Chingam, and the second one when Chingam holds two.

`tradition` decides the two festivals where Smartas and Vaishnavas reckon differently: `smarta` (default) reads Rama Navami at midday and Janmashtami at midnight, `vaishnava` reads both at sunrise, never joined with the tithi before. In New Delhi 2025 that moves Janmashtami from the 15th to the 16th of August.

Each entry carries both month names: amanta (new moon to new moon, South and West India) and purnimanta (full moon to full moon, North India). They differ only in the Krishna paksha: Diwali 2026 is in amanta Ashwina and purnimanta Kartika.

## Vrats

| Type | Rule |
|---|---|
| `ekadashi` | see below |
| `pradosh` | Trayodashi at pradosha, on two days the one it covers longer; named by weekday (Soma, Bhauma, Shani Pradosh) |
| `sankashti` | Krishna Chaturthi at moonrise; the moonrise is returned; named by the purnimanta month |
| `masik-shivaratri` | Krishna Chaturdashi at nishita |
| `purnima` | the Purnima vrat (Purnima in force at midday) and the bath day (Purnima at sunrise), which can be a day apart |
| `amavasya` | Darsha Amavasya (in force in the afternoon, the shraddha hour) and the bath day (at sunrise) |

**Ekadashi.** The Smarta day is the one Ekadashi holds at sunrise. When it holds at two sunrises, the first, unless Dashami touches it at arunodaya, in which case all fast on the second. When Dwadashi then touches no sunrise, the parana would fall in Trayodashi, so Smartas fast the day before. When Ekadashi touches no sunrise at all, the day it begins. The Vaishnava day refuses Dashami-viddha: Dashami at arunodaya moves the fast a day; a second sunrise in Ekadashi is the Gauna day; Dwadashi holding two sunrises (Vanjuli) moves the fast to its first day. `observance` is `both` when the days agree, otherwise there is one entry for `smarta` and one for `vaishnava`.

`parana` is the next morning's window to break the fast: never in Hari Vasara (the first quarter of Dwadashi), within Dwadashi, preferably in pratahkala; when Hari Vasara runs past pratahkala, after madhyahna to the end of aparahna; when Dwadashi has ended before sunrise, in pratahkala. `hariVasaraEnds` and `dwadashiEnds` are returned with it.

## Lunar months

`/vedic/calendar/months` lists the months touching the year. A month runs from new moon to new moon and takes the name of the sidereal sign the Sun is in at the opening new moon, plus one: Sun in Meena names Chaitra. A month with no sankranti inside is adhika and takes the name of the month after it; one with two is kshaya, and `kshayaOf` names the month it swallows. 2026 has Adhika Jyeshtha from 17 May to 15 June. The response also carries the twelve sankranti moments and the eras: Shaka (1948 from Chaitra 2026), Vikram Samvat from Chaitra (2083) and from Kartika as Gujarat counts it, and the sixty-year samvatsara name (Parabhava).

## Regional calendars

`calendar` is one of five.

| Calendar | Month starts | Year |
|---|---|---|
| `tamil` | sankranti before sunset: that day; after: the next | samvatsara name, from Chithirai |
| `malayalam` | sankranti within the first three fifths of daylight: that day; later: the next | Kollam era, from Chingam |
| `bengali` | sankranti between sunrise and midnight: the next day; after midnight: the day after | Bangabda, from Boishakh |
| `gujarati` | amanta lunar month, Sud and Vad | Vikram Samvat from Kartika (day after Diwali) |
| `marathi` | amanta lunar month | Shaka from Chaitra (Gudi Padwa) |

`/regional/months` gives each month's first and last civil day, length, sankranti or new moons and year. `/regional/date` converts one date: for the solar calendars the month and its day, for the lunisolar ones the month and the tithi at local sunrise.

```bash
curl https://api.astroway.info/v1/vedic/calendar/regional/date \
  -H "X-Api-Key: $ASTROWAY_KEY" -H "Content-Type: application/json" \
  -d '{ "calendar": "malayalam", "date": "2026-08-17", "latitude": 9.9312, "longitude": 76.2673, "timezone": "Asia/Kolkata" }'
```

## ICS feed

`GET /v1/vedic/calendar/ics` returns `text/calendar`: one all-day event per festival and vrat, with the rule, tithi window, parana and source in the description and a UID that stays the same between calls. Query parameters: `year`, `latitude`, `longitude`, `timezone`, `include` (`festivals`, `vrats` or single vrat types such as `ekadashi`, comma separated; default `festivals,vrats`) and `tradition`.

**Caution:**
The key travels in the `X-Api-Key` header, as on every endpoint, and calendar apps cannot send headers. Fetch the file on your server (once a year per place is enough) and serve it to your users from there. Never put a key in a URL.

```bash
curl "https://api.astroway.info/v1/vedic/calendar/ics?year=2026&latitude=28.6139&longitude=77.209&timezone=Asia/Kolkata&include=festivals,ekadashi" \
  -H "X-Api-Key: $ASTROWAY_KEY" -o hindu-2026.ics
```

## How it was checked

Against drikpanchang.com for 2025 and 2026: 323 of 325 festival dates for New Delhi, Chennai and New York agree, and on a holdout that was not used to set any rule (New Delhi 2024 and 2027, London 2026, Mumbai 2025) 204 of 214. Every difference is a festival whose tithi meets its kala on two days, where almanacs settle the tie differently (Diwali 2024 is the known case: 31 October or 1 November). Ekadashi Smarta and Vaishnava days for New Delhi 2024 to 2027 agree on every date but one; parana windows for 2026 are within a minute. Pradosh, Sankashti, Masik Shivaratri, Purnima and Amavasya for New Delhi 2025 and 2026 agree on every date.

**Note:**
Sankranti moments here run 5 to 8 minutes earlier than drikpanchang's on the same Lahiri ayanamsa, and tithi ends about a minute later. A regional month start or a festival whose condition falls within those minutes of a boundary can come out a day apart.