Muhurta (electional astrology) via API

Muhurta is the Vedic practice of electing an auspicious moment to begin an activity, and it is fully computable through an API because every factor it depends on is a deterministic function of date, time, and location. With Vedika you compute a Panchanga, read back the auspicious and inauspicious windows, score candidate timestamps on tithi, nakshatra, lagna, and active doshas, and return a ranked list of muhurats. This guide walks through the classical logic, the exact endpoint shapes, and a working example that scans a day for good windows.

What Muhurta actually computes

Electional astrology (Muhurta) answers a narrow, practical question: of all the moments in a window, which one is most suitable to start something? The classical texts that practitioners train on — Brihat Parashara Hora Shastra, Muhurta Chintamani by Daivajna Ramacharya, and the Panchanga tradition — reduce the answer to a handful of measurable limbs.

The five limbs of the Panchanga

• Tithi — the lunar day, the angular distance between Sun and Moon divided into 30 steps. Certain tithis (the rikta tithis: 4th, 9th, 14th) are generally avoided for beginnings.
• Vara — the weekday, each ruled by a planet, which conditions which activities suit the day.
• Nakshatra — the lunar mansion the Moon occupies; each of the 27 nakshatras has a fixed nature (movable, fixed, fierce, gentle, etc.) that suits specific activities.
• Yoga — one of 27 Sun–Moon combinations; a few (such as Vyatipata and Vaidhriti) are inauspicious.
• Karana — half a tithi; the Vishti (Bhadra) karana in particular is avoided for auspicious starts.

Beyond the five limbs

A complete Muhurta evaluation layers more on top of the Panchanga: the lagna (rising sign) at the candidate moment and the planets occupying or aspecting the kendras; inauspicious daily windows such as Rahu Kaal, Yamaganda, and Gulika Kaal; and benefic windows such as Abhijit Muhurta around solar noon. Active doshas for the specific activity — for example a marriage election checks for afflictions the matrimony tradition flags — are screened out as well.

Why an API beats a static muhurat table

Printed panchang almanacs and free muhurat lookup sites publish pre-computed tables for a fixed location, usually a single reference city. That breaks the moment your user is somewhere else: Rahu Kaal, sunrise-anchored windows, and the lagna all shift with latitude, longitude, and the date's sunrise. Computing on demand for the user's exact coordinates is the only way to stay correct.

Doing the astronomy yourself is the hard part. Tithi and nakshatra boundaries depend on precise lunar and solar longitudes, and a small error in planetary position moves a boundary by minutes — enough to flip whether a timestamp falls in a good or bad window. Vedika computes positions with the XALEN Ephemeris, Vedika's own open-source astronomical engine (Apache-2.0, published to crates.io, PyPI, and npm). It is validated against reference astronomical datasets including JPL DE440 and the swetest reference implementation, with roughly 2,200 tests; across a reproducible JPL DE440 benchmark, no chart deviated beyond 0.1° in planetary position. That is astronomical precision for the inputs — the interpretive Muhurta judgement on top of it is governed by the classical rules described above.

The endpoints you'll use

There are two layers. The AI query endpoint returns a reasoned answer and a recommended window; the V2 computation endpoints return raw Panchanga values you can score yourself. Most production integrations use both: V2 to enumerate and filter candidate timestamps, the query endpoint to explain the chosen one.

Authentication is a single header, x-api-key: vk_live_*, against base URL https://api.vedika.io. There is a free sandbox that needs no key — try the shapes against the sandbox before you wire up billing.

Asking for a Muhurta in natural language

The simplest path is to describe the activity and the window, and let Vedika AI elect the time. The birthDetails here represent the event location and the candidate moment, not a person's birth — Muhurta charts the moment of the activity.

curl -X POST https://api.vedika.io/api/v1/astrology/query \
  -H "x-api-key: vk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is an auspicious muhurta to start a new business on June 22, 2026 in Pune? Avoid Rahu Kaal and rikta tithis.",
    "birthDetails": {
      "datetime": "2026-06-22T09:00:00",
      "latitude": 18.5204,
      "longitude": 73.8567,
      "timezone": "Asia/Kolkata"
    }
  }'

The response cites the relevant Panchanga limbs and names the inauspicious windows it excluded, so the recommendation is auditable rather than a black box.

Scanning a day with the computation layer

For deterministic, high-volume scheduling you want to scan a range yourself. Pull the Panchanga and inauspicious-period boundaries once for the date, then iterate over candidate timestamps and score each one. The example below sketches the loop with a generic HTTP client.

import requests

BASE = "https://api.vedika.io"
HEADERS = {"x-api-key": "vk_live_xxx", "Content-Type": "application/json"}

def panchanga(dt, lat, lon, tz):
    body = {"datetime": dt, "latitude": lat, "longitude": lon, "timezone": tz}
    r = requests.post(f"{BASE}/v2/astrology/panchang", json=body, headers=HEADERS)
    r.raise_for_status()
    return r.json()

# Rikta tithis and the Vishti karana are classically avoided for new ventures.
RIKTA = {4, 9, 14}

def score_window(p):
    score = 100
    if p["tithi"]["number"] in RIKTA:
        score -= 40
    if p["karana"]["name"] == "Vishti":
        score -= 30
    # Prefer movable / gentle nakshatras for a launch; this is a coarse heuristic.
    if p["nakshatra"]["nature"] in ("movable", "gentle"):
        score += 15
    return score

# Walk 09:00-18:00 in 30-min steps, skip inauspicious periods, keep top score.
best = None
for hour in range(9, 18):
    for minute in (0, 30):
        dt = f"2026-06-22T{hour:02d}:{minute:02d}:00"
        p = panchanga(dt, 18.5204, 73.8567, "Asia/Kolkata")
        if p.get("inauspicious", {}).get("in_rahu_kaal"):
            continue
        s = score_window(p)
        if best is None or s > best[1]:
            best = (dt, s, p)

print("Best window:", best[0], "score", best[1])

Field names in the snippet are illustrative; check the live response shape in the sandbox or the docs for the exact keys. The pattern is what matters: compute the Panchanga per candidate, exclude inauspicious periods, score on classical rules, rank.

Designing your scoring rules

The example uses a coarse additive score on purpose — real Muhurta weighting is activity-specific, and you should encode the rules from the tradition you trust rather than invent numbers. A few principles keep the model honest.

• Match the activity to the nakshatra nature. Movable nakshatras suit travel and vehicle purchases; fixed ones suit construction and long-term commitments; gentle ones suit ceremonies. These categories come from the Muhurta tradition, not from arbitrary weighting.
• Hard-exclude, don't penalise, the truly inauspicious. Rahu Kaal, Yamaganda, Gulika Kaal, and the Vishti karana are typically removed from the candidate set entirely rather than docked points.
• Treat the lagna as a second-stage filter. Once you have a short list of clean Panchanga windows, evaluate the rising sign and kendra occupancy for each to break ties.
• Keep doshas activity-scoped. A marriage Muhurta screens for the afflictions the matrimony tradition flags; a property purchase has a different checklist. See the Mangal Dosha API guide for how dosha computation works end to end.

Muhurta, horary, and where KP fits

Muhurta (electing a future time) is distinct from Prashna or horary (reading the chart of the moment a question is asked), but they share machinery: both turn on the lagna and Panchanga of a specific instant. Vedika carries all three Vedic-adjacent systems in one API — Vedic (sidereal), Western (tropical), and KP — so a KP practitioner can request sub-lord and significator analysis for the same instant a Muhurta query is built around. If your product blends timing advice with a question-answer flow, you can reuse one integration for both.

Pricing and scale

A day-scan of 30-minute windows is roughly 18 Panchanga calls; a finer 10-minute scan is closer to 54. Computation calls are inexpensive, and the AI reasoning call is the costlier of the two layers, so most integrations scan cheaply with V2 and reserve the query endpoint for the final recommendation. Subscriptions start at $12/mo (Starter), with Professional at $60, Business at $120 (adds the fast path and voice), and Enterprise at $240; per-query computation runs $0.01–$0.05. Full tiers are on the pricing page.

For comparison, dedicated astrology APIs like Prokerala, AstrologyAPI.com, and RoxyAPI all offer Panchanga and muhurat endpoints and are well-established choices. Where Vedika differs is breadth in one surface: 700+ operations across 25 domains (704 enumerated as of June 2026), three zodiac systems plus Jaimini, Tajaka, Lal Kitab and numerology, 30 languages, and a transparent open-source ephemeris you can run locally for offline boundary calculations.

Key facts

• Muhurta is computed from the five Panchanga limbs (tithi, vara, nakshatra, yoga, karana) plus lagna and active doshas — all deterministic from date, time, and location.
• Main AI path: POST /api/v1/astrology/query; streaming via /api/v1/astrology/query/stream; raw Panchanga via POST /v2/astrology/*.
• Auth is x-api-key: vk_live_* against https://api.vedika.io; a free sandbox needs no key.
• Positions come from the XALEN Ephemeris (Apache-2.0, ~2,200 tests), validated against JPL DE440 and swetest with no chart deviating beyond 0.1° across a reproducible JPL DE440 benchmark — astronomical precision for the timing inputs.
• Rahu Kaal, Yamaganda, Gulika Kaal, and the Vishti karana are hard-excluded; Abhijit Muhurta is a preferred window.
• Vedic, Western, and KP share one API, so Muhurta and horary flows can reuse a single integration.
• Subscriptions $12–$240/mo; per-query $0.01–$0.05.

Frequently asked questions

The questions below summarise the most common integration concerns for electional timing. For deeper Panchanga mechanics, see the Nakshatra developer's guide; for the timing-of-events side, the Vimshottari Dasha explainer.