GET/v1/astro/panchanga/festivals

Hindu festival and vrat 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 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 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.

Request parameters

yearrequired

integer

Calendar year

locationoptional

string | null

City name

latitudeoptional

number | null

longitudeoptional

number | null

timezoneoptional

string | null

IANA timezone

categoriesoptional

string | null

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 fields

success

boolean

True if the request succeeded

message

string

Human-readable status message

data

object

data.year

integer

Calendar year for which festivals are computed.

data.timezone

string

IANA timezone used for sunrise-based tithi calculations.

data.total

integer

Number of entries returned.

data.festivals

array[object]

Festivals sorted chronologically by date.

data.festivals[].name

string

Festival name.

data.festivals[].date

string

Festival date in YYYY-MM-DD format (start date for a period).

data.festivals[].type

string

'solar' (sankranti-based), 'tithi' (lunar day-based) or 'eclipse'.

data.festivals[].description

string

Classical basis for the date: the tithi or sankranti and the rule that picks the day.

data.festivals[].significance

string

Cultural and religious significance.

data.festivals[].id

string | null

Stable identifier, e.g. diwali, ekadashi, pradosh_vrat, pitru_paksha.

data.festivals[].category

string | null

festival, vrat, sankranti, eclipse or period.

data.festivals[].end_date

string | null

Last day, for a period (Pitru Paksha, Chaturmas, Adhik Maas, ...).

data.festivals[].masa

FestivalMasa | null

data.festivals[].paksha

string | null

data.festivals[].tithi

FestivalTithi | null

The tithi the festival follows, with its exact start and end.

data.festivals[].rule

string | null

Part of the day in which the tithi must prevail: sunrise, purvahna, madhyahna, aparahna, sayahna, pradosh, nishita, moonrise, arunodaya, or ekadashi (Smarta rule).

data.festivals[].observance_window

FestivalWindow | null

Puja window on the day: that part of the day while the tithi lasts.

data.festivals[].note

string | null

Why the date moved (Bhadra, a short tithi, ...).

data.festivals[].sankranti

FestivalSankranti | null

data.festivals[].eclipse

FestivalEclipse | null

Errors

authentication_failed

Missing or invalid API key.

ephemeris_unavailable

Upstream ephemeris service error.

insufficient_tier

Reserved; product endpoints are not feature-gated by plan (quota differs by tier).

internal_error

Unexpected server error.

ip_rate_limit_exceeded

Too many requests in a short window.

payload_too_large

Request body exceeds the size limit.

resource_not_found

Referenced resource was not found.

validation_error

Request body failed schema validation.

Related endpoints

• Choghadiya periods
• Daily Panchanga
• Monthly Panchanga calendar
• Monthly Panchanga calendar (JSON body)
• Planetary hours (Hora)
• Rahu Kaal, Gulika Kaal, Yamaganda Kaal
• Tamil Panchanga

Request

GET·application/json

curl

curl -X GET "https://api.asterwise.com/v1/astro/panchanga/festivals?year=2026&latitude=28.6139&longitude=77.209&timezone=Asia%2FKolkata" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import asterwise
from asterwise.api.astrology_api import AstrologyApi

configuration = asterwise.Configuration(
    host="https://api.asterwise.com",
    access_token="YOUR_API_KEY",
)

with asterwise.ApiClient(configuration) as client:
    api = AstrologyApi(client)
    result = api.panchanga_festivals(year=2026,
    latitude=28.6139,
    longitude=77.209,
    timezone="Asia/Kolkata")
    print(result)

TypeScript

import { createClient, createConfig, panchangaFestivals } from 'asterwise';

const client = createClient(createConfig({
  baseUrl: 'https://api.asterwise.com',
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
}));

const result = await panchangaFestivals({
  client,
  query: {
      "year": 2026,
      "latitude": 28.6139,
      "longitude": 77.209,
      "timezone": "Asia/Kolkata"
  },
});

console.log(result.data);

Response

200 OK·application/jsonsigned

{
  "success": true,
  "message": "success",
  "data": {
    "year": 2026,
    "timezone": "Asia/Kolkata",
    "total": 52,
    "festivals": [
      {
        "id": "lohri",
        "name": "Lohri",
        "date": "2026-01-13",
        "type": "solar",
        "category": "festival",
        "description": "The eve of Makar Sankranti.",
        "significance": "Punjabi winter harvest festival with a bonfire, songs and sesame sweets.",
        "sankranti": {
          "rashi": "Makara",
          "moment": "2026-01-14T15:07:20+05:30"
        }
      },
      {
        "id": "makar_sankranti",
        "name": "Makar Sankranti",
        "date": "2026-01-14",
        "type": "solar",
        "category": "festival",
        "description": "Sun's sidereal transit into Makara (Capricorn). Observed on the day of the transit; a transit after sunset is observed t…",
        "significance": "Harvest festival. Uttarayana begins. Associated with kite flying, sesame sweets (til-gul), and holy dips in rivers. Know…",
        "sankranti": {
          "rashi": "Makara",
          "moment": "2026-01-14T15:07:20+05:30"
        }
      },
      "... and 50 more items"
    ]
  }
}