---
title: "Hindu festival and vrat calendar"
method: GET
path: "/v1/astro/panchanga/festivals"
tags: ["Astrology"]
---

# Hindu festival and vrat calendar

`GET /v1/astro/panchanga/festivals`

## Request

- Base URL: `https://api.asterwise.com`
- URL: `https://api.asterwise.com/v1/astro/panchanga/festivals`
- Auth: HTTP bearer

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 detected from new moons and sankrantis), its tithi, and the part of the day in which the tithi must prevail (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. Categories: festival (about 50 named festivals), vrat (every Ekadashi, Pradosh, Sankashti Chaturthi, Masik Shivaratri, Purnima, the Purnima vrat (fast) day and Amavasya), sankranti (12 solar ingresses), eclipse (with local visibility and contact times), period (Adhik Maas, Chaturmas, Pitru Paksha, Navratri, Holashtak, Kharmas). By default only the named festivals are returned; pass `categories` for the rest. Lahiri ayanamsa.

## Query parameters

- `year` integer, required: Calendar year
- `location` string, nullable: City name
- `latitude` number, nullable: Latitude in decimal degrees, north positive. Use with longitude and timezone instead of location.
- `longitude` number, nullable: Longitude in decimal degrees, east positive. Use with latitude and timezone instead of location.
- `timezone` string, nullable: IANA timezone
- `categories` string, nullable: Comma-separated subset of festival, vrat, sankranti, eclipse, period. Default: festival (the named festivals). Pass e.g. 'festival,vrat,period' for Ekadashis, Pradosh, Sankashti, Purnima and Amavasya, Adhik Maas and Pitru Paksha, or 'eclipse' for eclipses.

## Response `200`

Successful Response

- ApiResponseFestivalCalendarResponse
  - `success` boolean: True if the request succeeded
  - `message` string: Human-readable status message
  - `data` FestivalCalendarResponse, required
    - `year` integer, required: Calendar year for which festivals are computed.
    - `timezone` string, required: IANA timezone used for sunrise-based tithi calculations.
    - `total` integer, required: Number of entries returned.
    - `festivals` FestivalEntry[], required: Festivals sorted chronologically by date.
      - `name` string, required: Festival name.
      - `date` string, required: Festival date in YYYY-MM-DD format (start date for a period).
      - `type` string, required: 'solar' (sankranti-based), 'tithi' (lunar day-based) or 'eclipse'.
      - `description` string, required: Classical basis for the date: the tithi or sankranti and the rule that picks the day.
      - `significance` string, required: Cultural and religious significance.
      - `id` string, nullable: Stable identifier, e.g. diwali, ekadashi, pradosh_vrat, pitru_paksha.
      - `category` string, nullable: festival, vrat, sankranti, eclipse or period.
      - `end_date` string, nullable: Last day, for a period (Pitru Paksha, Chaturmas, Adhik Maas, ...).
      - `masa` FestivalMasa
        - `amanta` string, required: Amanta month name (with 'Adhik' for an intercalary month).
        - `purnimanta` string, required: Purnimanta month name.
        - `is_adhik` boolean, required
      - `paksha` string, nullable
      - `tithi` FestivalTithi
        - `number` integer, required: 1 to 30.
        - `name` string, required
        - `start` string, required: Tithi start, ISO 8601 local time.
        - `end` string, required: Tithi end, ISO 8601 local time.
      - `rule` string, nullable: Part of the day in which the tithi prevails on the chosen day: sunrise, purvahna, madhyahna, aparahna, sayahna, pradosh, nishita, moonrise, arunodaya, or ekadashi (Smarta rule). A rule with a fallback reports the part of the day that decided (the Purnima vrat: madhyahna, or sunrise when Purnima holds no Madhyahna; Vat Purnima: moonrise, or sunrise when no moonrise falls in Purnima). day_after: kept the day after another festival (Holi, after Holika Dahan); its tithi is the one it is named for and it has no observance_window.
      - `observance_window` FestivalWindow
        - `start` string, required
        - `end` string, required
      - `tithi_at_moonrise` boolean, nullable: Moonrise rules only: true when the tithi is still running at the moonrise in observance_window; false when the day was chosen because no moonrise fell in the tithi (it ended before the Moon rose) and the moonrise is shown for breaking the fast.
      - `note` string, nullable: Why the date moved (Bhadra, a short tithi, ...).
      - `sankranti` FestivalSankranti
        - `rashi` string, required: Sidereal sign the Sun enters.
        - `moment` string, required: Ingress instant, ISO 8601 local time.
      - `eclipse` FestivalEclipse
        - `body` string, required: sun or moon.
        - `kind` string, required: total, annular, hybrid, partial or penumbral.
        - `greatest` string, required: Instant of greatest eclipse (anywhere on Earth), local time.
        - `visible_here` boolean, required: Whether any part is visible from the requested location.
        - `local` EclipseLocal
          - `begins` string, nullable: First contact seen from the location (null when it rises already eclipsed).
          - `maximum` string, required: Greatest phase seen from the location (at moonrise when the Moon rises eclipsed).
          - `ends` string, nullable: Last contact of the umbral (or penumbral) phase.
          - `moonrise` string, nullable: Moonrise, for a lunar eclipse that is in progress at moonrise.

## Other responses

- `401`: Authentication failed
- `403`: Authorization failed
- `404`: Resource not found
- `413`: Payload too large
- `422`: Validation error
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream provider error
- `503`: Service unavailable

---

[API](https://skmtc.dev/asterwise/apis/asterwise-api.md) · [All operations](https://skmtc.dev/asterwise/apis/asterwise-api/llms.txt) · [OpenAPI document](https://skmtc.dev/asterwise/apis/asterwise-api/revisions/3c4bbb1194e2?raw)