Auspicious Period API

Auspicious Period

The Auspicious Period API identifies and returns all favourable and unfavourable time windows for a given date and geographic location, based on classical Vedic astrology and Panchang principles. Rather than returning the full almanac, this endpoint focuses specifically on the timing dimension — surfacing the precise start and end times of auspicious and inauspicious periods throughout the day so that users can plan important activities accordingly.

What This API Does

This endpoint analyses the Panchang elements for the specified date, time, and location and derives a structured list of named time periods that are considered either auspicious (Shubh) or inauspicious (Ashubh) according to Vedic tradition. Calculations are performed using the astronomical sunrise for the given coordinates, and the Ayanamsha system is configurable via a request header to support different Vedic schools.

Data Returned

The response provides a comprehensive breakdown of daily time periods, typically including:

• Abhijit Muhurta — The most universally auspicious time window of the day, occurring near solar noon

• Brahma Muhurta — The highly auspicious pre-dawn period ideal for spiritual practice and new beginnings

• Rahu Kalam — The daily inauspicious period governed by Rahu, to be avoided for important undertakings

• Gulika Kalam — An inauspicious window associated with Gulika (son of Saturn)

• Yamaganda — An inauspicious period associated with Yama, the lord of death

• Dur Muhurta — Inauspicious time slots during the day that should be avoided

• Varjyam — A period considered particularly unfavourable for all activities

• Amrit Kalam — An auspicious window considered highly beneficial for important tasks

• Choghadiya — The traditional Gujarati/Rajasthani system of eight daily time segments, each classified as auspicious, inauspicious, or neutral

• Hora — Planetary hours of the day, each ruled by a specific planet, indicating the nature of activities best suited to that window

• Sunrise and Sunset times — The anchor points used to compute all period timings

Main Use Cases

• Muhurta selection — Helping individuals and astrologers identify the best time windows for starting important activities such as travel, business launches, property purchases, medical procedures, or ceremonies

• Daily planning apps — Powering a "best time to act" feature in astrology, wellness, or productivity apps that surface auspicious windows for the user's current location

• Wedding and event planning — Providing precise auspicious and inauspicious periods to help plan the timing of rituals, ceremonies, and celebrations

• Devotional and spiritual apps — Surfacing Brahma Muhurta and other spiritually significant windows for meditation, prayer, and worship scheduling

• Avoidance scheduling — Enabling users to steer clear of Rahu Kalam, Gulika Kalam, Yamaganda, and other inauspicious periods when scheduling important meetings or decisions

Key Functionality

• Focused on timing — Unlike general Panchang endpoints, this API is purpose-built to return a complete, structured list of named time periods with precise start and end times, making it directly actionable for scheduling

• Covers both auspicious and inauspicious periods — Returns the full spectrum of Vedic time classifications in a single response, from the most favourable (Abhijit Muhurta, Amrit Kalam) to the most unfavourable (Rahu Kalam, Varjyam)

• Sunrise-anchored calculations — All period timings are derived from the actual astronomical sunrise at the specified location, ensuring traditional accuracy

• Location-aware — Uses latitude, longitude, and timezone offset to compute sunrise and derive all period timings specific to any location worldwide

• Configurable Ayanamsha — The X-Ayanamsha header allows selection of the sidereal correction system (e.g., Lahiri, Raman, KP), ensuring compatibility with different Vedic astrology traditions

• Multi-language support — The Accept-Language header enables period names and labels to be returned in the preferred regional or vernacular language