Festival Calendar
asterwise_get_festival_calendar
Computes all major Hindu festival dates for a given year and location. Returns 20 pan-Hindu festivals including solar sankrantis (Makar Sankranti, Vaisakhi) and tithi-based festivals (Diwali, Holi, Dussehra, Janmashtami, Ganesh Chaturthi, Ram Navami, and 12 others).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
year | integer | yes | |
response_format | enum: markdown, json | no | |
location | string/null | no | |
latitude | number/null | no | |
longitude | number/null | no | |
timezone | string/null | no |
What it covers
All dates are astronomically computed — no hardcoded calendar dates. Solar festivals (Makar Sankranti, Vaisakhi) use exact Swiss Ephemeris Sun ingress into Lahiri sidereal signs. Tithi festivals (all others) use Sun-Moon elongation at local sunrise: elongation = (moon_lon - sun_lon) % 360, tithi_index = int(elongation / 12), indices 0-14 = Shukla Paksha tithi 1-15, indices 15-29 = Krishna Paksha tithi 1-15. Location is required for sunrise-based tithi determination — the same astronomical event may fall on different calendar dates at different locations.
Workflow
BEFORE: None — standalone.
AFTER: asterwise_get_panchanga — drill into full Panchanga detail for any specific festival date.
Input
year: integer 1900-2100.
Either location (city name) OR latitude + longitude + timezone must be provided.
Output contract
data.year (int)
data.timezone (string — IANA timezone used)
data.total (int — number of festivals found)
data.festivals[] — chronologically sorted:
name (string — festival name)
date (string — YYYY-MM-DD)
type (string — 'solar' or 'tithi')
description (string — classical basis, e.g. which tithi of which lunar month)
significance (string — cultural and religious significance)
Response format
response_format=json serialises the complete response as indented JSON — use this for programmatic parsing, typed clients, and downstream tool chaining. response_format=markdown renders the same data as a human-readable report. Both modes return identical underlying data — no fields are added, removed, or filtered by either mode.
Compute class
SLOW_COMPUTE — scans all 365 days of the year per tithi festival (up to 20 date scans).
Errors
INVALID_PARAMS (local): None.
INTERNAL_ERROR: Any upstream API failure or timeout → MCP INTERNAL_ERROR
Edge cases:
— Sunrise-based tithi may differ by one day from printed almanac calendars (which use midnight or fixed-time rules).
— Rare years where a tithi is skipped may cause a festival to not be found (returns total < 20).
Do not confuse with
asterwise_get_panchanga_calendar — full Panchanga for every day of a month; not festival-specific.
asterwise_get_muhurta — finds auspicious windows for activities; not a festival calendar.
Connect
Remote MCP endpoint: https://mcp.asterwise.com/mcp. Authenticate with Authorization: Bearer <API key> or OAuth. See the MCP setup guide.