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, 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.

Request parameters

yearrequired

integer

Calendar year

locationoptional

string | null

City name

latitudeoptional

number | null

Latitude in decimal degrees, north positive. Use with longitude and timezone instead of location.

longitudeoptional

number | null

Longitude in decimal degrees, east positive. Use with latitude and timezone instead of location.

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 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.

data.festivals[].observance_window

FestivalWindow | null

Puja window on the day: that part of the day while the tithi lasts. For a moonrise rule (Karva Chauth, Sankashti Chaturthi, Vat Purnima) it is the moonrise instant of the day, when the fast is broken, even if the tithi has ended by then (see tithi_at_moonrise).

data.festivals[].tithi_at_moonrise

boolean | null

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.

data.festivals[].note

string | null

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

data.festivals[].sankranti

FestivalSankranti | null

data.festivals[].eclipse

FestivalEclipse | null

Errors

api_key_invalid

Invalid API key format.

api_key_missing

API key is missing. Include it in the Authorization header as 'Bearer YOUR_KEY'.

api_key_not_found

The provided API key was not found. Verify the key in your Asterwise dashboard.

api_key_revoked

This API key has been revoked.

burst_limit_exceeded

Too many requests per minute. Please slow down.

internal_error

Something went wrong on our end. Please try again, or contact [email protected] if the problem persists. Include your request_id when contacting support.

ip_rate_limit_exceeded

Too many requests from this IP address. Please slow down.

monthly_usage_limit_exceeded

Monthly API call limit reached. Upgrade your plan to continue.

payload_too_large

Request body exceeds maximum allowed size of 64KB.

subscription_expired

Your subscription has expired. Please renew at asterwise.com/dashboard to continue.

validation_error

The request couldn't be processed. See the 'details' field for specific field-level issues.

Related endpoints

• Choghadiya periods
• Daily Panchanga
• Monthly Panchanga calendar
• 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"
    ]
  }
}