Festival Calendar
asterwise_get_festival_calendar
Hindu festivals, vrats, sankrantis, eclipses and periods for a year at a location. Each lunar festival is fixed by its lunar month (amanta, with Adhik months found from new moons and sankrantis), its tithi, and the part of the day the tithi must hold (sunrise, forenoon, Madhyahna, Aparahna, Pradosh, Nishita, moonrise), with the classical tie-breaks when a tithi spans two days, Bhadra rules for Holika Dahan and Raksha Bandhan, and the Smarta Ekadashi rule. Checked against Drik Panchang (New Delhi).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
year | integer | yes | Calendar year, e.g. 2026. |
lat | number | yes | Latitude in decimal degrees, north positive. |
lon | number | yes | Longitude in decimal degrees, east positive. |
timezone | string | no | IANA timezone of the location. |
categories | array/null | no | Which entries to return: festival (default, about 50 named festivals), vrat (Ekadashi, Pradosh, Sankashti, Purnima, Amavasya), sankranti, eclipse, period (Adhik Maas, Pitru Paksha, Chaturmas, Navratri, Holashtak, Kharmas). |
response_format | enum: markdown, json | no | Output format: 'markdown' (default) for a readable report, or 'json' for the raw structured payload. |
What it covers
Categories: festival (about 50: Diwali, Holi, Dussehra, Janmashtami, Karva Chauth, Govardhan, Chhath, Chaitra Navratri ...), vrat (every Ekadashi, Pradosh, Sankashti Chaturthi, Masik Shivaratri, Purnima, Amavasya), sankranti (12 solar ingresses), eclipse (with local visibility and contact times), period (Adhik Maas, Chaturmas, Pitru Paksha, both Navratris, Holashtak, Kharmas). Dates depend on the location's sunrise and sunset.
Workflow
BEFORE: asterwise_geocode — when you only have a place name.
AFTER: asterwise_get_panchanga — the day's limbs and timings for a festival date.
Input
year (1900-2100), lat, lon, timezone (IANA, default Asia/Kolkata). categories: optional list of festival, vrat, sankranti, eclipse, period; the default is ["festival"] (about 50 named festivals). Add "vrat" for every Ekadashi, Pradosh, Sankashti, Purnima and Amavasya, "period" for Adhik Maas, Pitru Paksha and Chaturmas, "eclipse" for eclipses.
Output contract
data.festivals[] sorted by date: id, name, date, end_date (periods), type (solar, tithi, eclipse), category, description (the rule used), significance, masa {amanta, purnimanta, is_adhik}, paksha, tithi {number, name, start, end}, rule, observance_window {start, end} (puja window), note (when Bhadra or a short tithi moved the date), sankranti {rashi, moment}, eclipse {body, kind, greatest, visible_here, local}.
Errors
INVALID_PARAMS (local): bad year or coordinates, unknown category. INTERNAL_ERROR: upstream failure.
Do not confuse with
asterwise_get_panchanga_calendar — daily limbs for a month, not festivals.
asterwise_get_muhurta — auspicious windows for an activity, not festival dates.
Connect
Remote MCP endpoint: https://mcp.asterwise.com/mcp. Authenticate with Authorization: Bearer <API key> or OAuth. See the MCP setup guide.