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

Six endpoints that turn the 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.

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.

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.

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.