POST/v1/astro/muhurta
Muhurta — Auspicious Timing
Finds and ranks auspicious time windows for an activity between two dates (up to a year) at a location. The range is cut at every change of tithi, nakshatra, yoga, karana, lagna, sunrise and sunset and at the edges of Rahu Kaal, Yamaganda, Gulika, Durmuhurta, Varjyam and Bhadra, so windows start and end at exact moments. A moment is ruled out when the season bars the activity (Chaturmas, Adhik Maas, Pitru Paksha, Kharmas, Holashtak, Guru or Shukra asta, Panchaka, per activity), when its nakshatra, tithi or weekday is not one the activity allows, or when it falls in an inauspicious period. Survivors are scored 0-100 and returned with ISO 8601 start_at and end_at, the civil date and the panchanga day, the reasons and cautions (the earlier fields, including HH:MM start and end on the panchanga day's date, are still returned). Optional participants (up to two) add Tarabala and Chandrabala. Activities: marriage, griha_pravesh, business, travel, naming_ceremony, vehicle_purchase, property_purchase, mundan, annaprashan, upanayana, vidyarambha.
Request parameters
event_typerequired
string
Activity. One of: marriage; griha_pravesh (housewarming); business (starting a business or shop); travel; naming_ceremony; vehicle_purchase; property_purchase; mundan (first haircut); annaprashan (first solid food); upanayana (sacred thread); vidyarambha (beginning education).
from_daterequired
string
Start date in YYYY-MM-DD format (inclusive)
to_daterequired
string
End date in YYYY-MM-DD format (inclusive). At most 366 days after from_date.
locationoptional
string | null
City name, resolved to latitude, longitude and timezone. Not needed when those are given.
latitudeoptional
number | null
Location latitude
longitudeoptional
number | null
Location longitude
timezoneoptional
string | null
IANA timezone string e.g. Asia/Kolkata
ayanamsaoptional
string
top_noptional
integer
Number of windows to return (1-50)
max_windows_per_dayoptional
integer
At most this many windows per day, so results spread across dates (1-10).
min_duration_minutesoptional
integer
Drop windows shorter than this (1-240 minutes).
participantsoptional
array[MuhurtaParticipant] | null
Up to two people (e.g. bride and groom). Adds Tarabala and Chandrabala: a Naidhana tara or the Moon in the 8th house from a participant's Moon rules a moment out.
Response fields
success
boolean
True if the request succeeded
message
string
Human-readable status message
data
object
data.event_type
string
data.activity
string
data.from_date
string
data.to_date
string
data.timezone
string
data.ayanamsa
string
data.criteria
object
data.criteria.nakshatras
array[string]
data.criteria.recommended_nakshatras
array[string]
data.criteria.tithis
array[string]
data.criteria.weekdays
array[string]
data.criteria.preferred_lagnas
array[string]
data.criteria.avoided_seasons
array[string]
data.criteria.avoided_periods
array[string]
data.criteria.daytime_only
boolean
data.total_windows_found
integer
Valid windows in the range before top_n is applied.
data.total_windows_evaluated
integer
Pieces of time examined (cut at every change).
data.excluded_minutes
object
Minutes ruled out, by first reason: chaturmas, adhik_maas, pitru_paksha, kharmas, holashtak, guru_asta, shukra_asta, panchaka, night, weekday, tithi, nakshatra, yoga, rahu_kaal, yamaganda, gulika, durmuhurta, varjyam, bhadra, tarabala, chandrabala.
data.top_windows
array[object]
data.top_windows[].date
string
Panchanga day (the date of the sunrise that opens it). A window after midnight carries the previous calendar date here. Kept from the earlier Choghadiya-slot response; prefer civil_date and start_at.
data.top_windows[].start
string
Start, HH:MM local time. Kept from the earlier Choghadiya-slot response; prefer start_at.
data.top_windows[].end
string
End, HH:MM local time. Kept from the earlier Choghadiya-slot response; prefer end_at.
data.top_windows[].score
integer
0-100.
data.top_windows[].choghadiya
string
Choghadiya at the window's start.
data.top_windows[].choghadiya_type
string
data.top_windows[].yoga
string
Panchanga yoga name.
data.top_windows[].vara
string
Weekday name (Sanskrit).
data.top_windows[].vara_number
integer
1 = Sunday ... 7 = Saturday.
data.top_windows[].tithi
string
Tithi name; see paksha and tithi_number.
data.top_windows[].tithi_number
integer
1-30 (16-30 Krishna).
data.top_windows[].reason
string
Reasons joined into one line. Kept from the earlier Choghadiya-slot response; prefer reasons.
data.top_windows[].is_rahu_kaal
boolean
Always false: Rahu Kaal is excluded from every window.
data.top_windows[].is_abhijit
boolean
data.top_windows[].is_amrita_siddhi
boolean
data.top_windows[].is_sarvartha_siddhi
boolean
data.top_windows[].start_at
string
Window start, ISO 8601 local time with offset.
data.top_windows[].end_at
string
Window end, ISO 8601 local time with offset.
data.top_windows[].civil_date
string
Calendar date on which the window starts.
data.top_windows[].panchanga_day
string
Same as date: the sunrise date of the panchanga day.
data.top_windows[].duration_minutes
number
data.top_windows[].grade
string
Excellent (85+), Good (70+) or Acceptable.
data.top_windows[].paksha
string
data.top_windows[].nakshatra
object
data.top_windows[].nakshatra.number
integer
data.top_windows[].nakshatra.name
string
data.top_windows[].yoga_number
integer
data.top_windows[].karana
string
data.top_windows[].vara_lord
string
data.top_windows[].lagna
MuhurtaLagna | null
Rising sign, for activities that use lagna.
data.top_windows[].masa
string
Amanta lunar month.
data.top_windows[].is_guru_pushya
boolean
data.top_windows[].is_ravi_pushya
boolean
data.top_windows[].reasons
array[string]
What makes the window good.
data.top_windows[].cautions
array[string]
Weaker points of an otherwise valid window.
data.top_windows[].tarabala
array[MuhurtaTara] | null
data.top_windows[].chandrabala
array[MuhurtaChandra] | null
data.notes
array[string]
Errors
Missing or invalid API key.
Upstream ephemeris service error.
Reserved; product endpoints are not feature-gated by plan (quota differs by tier).
Unexpected server error.
Too many requests in a short window.
Request body exceeds the size limit.
Referenced resource was not found.
Request body failed schema validation.