# Muhurat — electional astrology

Muhurat is Vedic electional astrology: picking an auspicious moment to start something important. Unlike natal astrology, the chart is built _for a future moment_ — and the algorithm scans a window of dates/times looking for when panchang factors (tithi, nakshatra, yoga, karana, vara, lagna) are most favourable for the specific event.

<Aside type="tip">
**How muhurat endpoints work.** Input: search window (start/end date, location, event duration). Output: ranked slots with a score, the favourable/unfavourable panchang elements, and a list of "avoid" periods (Rahu Kaal, Yamaganda, Gulika Kaal).
</Aside>

## What we compute

Each endpoint checks a distinct rule set:

- **marriage** — Saptapadi time: auspicious tithis (2, 3, 5, 7, 10, 11, 12, 13), nakshatras (Rohini, Mrigashira, Uttara Phalguni, Hasta, Swati, Anuradha, Mula, Uttara Ashadha, Uttara Bhadrapada, Revati), avoidance of Manglik-incompatible windows.
- **vehicle-purchase** — Mercury/Venus strong, avoiding Astha (Venus combust), Bhadra karana.
- **business-start** — Jupiter-aspected lagna, 10th house free of malefics, Chandra Bala.
- **travel** — Dishashool (direction of the day), mobility nakshatras, avoiding Yamaganda.
- **naming-ceremony (Namakaran)** — 11th or 12th day after birth; nakshatras favourable for the name.
- **surgery** — avoid Sankranti, Saturday, Chandrashtama; Mars/Saturn-related rules.
- **education-start (Vidyarambh)** — Wednesday/Thursday + Mercury/Jupiter strong + knowledge nakshatras (Hasta, Pushya, Sravana, Revati).
- **investment** — 2nd and 11th house support, Jupiter and Venus backing.
- **property-purchase** — 4th house clear, Saturn-aspected, avoid Mars in 4th.
- **griha-pravesh (housewarming)** — Uttarayana (northern solar arc), avoiding monsoon season, stability nakshatras (Anuradha, Uttara*).
- **engagement** — lighter requirements than marriage, same panchang logic.
- **court-case** — Mars-controlled, lagna lord strong, opponent significator weak.

## Endpoints

| Endpoint | Credits | Event |
|---|---|---|
| `/v1/vedic/muhurat/marriage` | 50 | Marriage (saptapadi time) |
| `/v1/vedic/muhurat/engagement` | 30 | Engagement |
| `/v1/vedic/muhurat/naming-ceremony` | 30 | Namakaran (naming a newborn) |
| `/v1/vedic/muhurat/griha-pravesh` | 50 | Housewarming |
| `/v1/vedic/muhurat/property-purchase` | 30 | Property purchase |
| `/v1/vedic/muhurat/vehicle-purchase` | 30 | Vehicle purchase |
| `/v1/vedic/muhurat/business-start` | 50 | Business start |
| `/v1/vedic/muhurat/investment` | 30 | Investment |
| `/v1/vedic/muhurat/education-start` | 30 | Vidyarambh — start of studies |
| `/v1/vedic/muhurat/travel` | 30 | Travel |
| `/v1/vedic/muhurat/surgery` | 30 | Surgery |
| `/v1/vedic/muhurat/court-case` | 30 | Court case / legal proceedings |

## Example

<Tabs>
  <TabItem label="cURL">
    ```bash frame="terminal"
    curl -X POST https://api.astroway.info/v1/vedic/muhurat/marriage \
      -H "X-Api-Key: aw_live_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "start_date": "2026-09-01",
        "end_date": "2026-12-31",
        "latitude": 28.6139,
        "longitude": 77.2090,
        "timezoneOffset": 5.5,
        "duration_hours": 3,
        "ayanamsa": "lahiri",
        "limit": 10
      }'
    ```
  </TabItem>
  <TabItem label="Node.js">
    ```ts
    const r = await fetch('https://api.astroway.info/v1/vedic/muhurat/business-start', {
      method: 'POST',
      headers: {
        'X-Api-Key': process.env.ASTROWAY_API_KEY!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        start_date: '2026-09-01',
        end_date: '2026-12-31',
        latitude: 50.4501,
        longitude: 30.5234,
        timezoneOffset: 3,
        duration_hours: 2,
        ayanamsa: 'lahiri',
        limit: 5,
      }),
    });
    const { data } = await r.json();
    for (const slot of data.slots) {
      console.log(`${slot.start} → ${slot.end}: score ${slot.score}/100 (${slot.verdict})`);
      console.log(`  Tithi: ${slot.panchang.tithi}, Nakshatra: ${slot.panchang.nakshatra}`);
    }
    ```
  </TabItem>
  <TabItem label="Python">
    ```python

    r = requests.post(
        'https://api.astroway.info/v1/vedic/muhurat/travel',
        headers={'X-Api-Key': os.environ['ASTROWAY_API_KEY']},
        json={
            'start_date': '2026-09-01',
            'end_date': '2026-09-30',
            'latitude': 50.4501,
            'longitude': 30.5234,
            'timezoneOffset': 3,
            'duration_hours': 1,
            'ayanamsa': 'lahiri',
            'limit': 10,
        },
    )
    for slot in r.json()['data']['slots']:
        print(f"{slot['start']} → {slot['end']}: {slot['score']}/100 ({slot['verdict']})")
    ```
  </TabItem>
</Tabs>

Sample response (`marriage`, abbreviated):

```json
{
  "data": {
    "event": "marriage",
    "window": { "start": "2026-09-01", "end": "2026-12-31" },
    "location": { "latitude": 28.6139, "longitude": 77.209, "timezone_offset": 5.5 },
    "slots": [
      {
        "start": "2026-11-12T07:24:00+05:30",
        "end":   "2026-11-12T10:24:00+05:30",
        "score": 84,
        "verdict": "excellent",
        "panchang": {
          "tithi": "Shukla Ekadashi",
          "nakshatra": "Rohini",
          "yoga": "Siddhi",
          "karana": "Vanij",
          "vara": "Thursday"
        },
        "factors_positive": ["Tithi auspicious", "Nakshatra Rohini", "Thursday", "No Rahu Kaal"],
        "factors_negative": []
      }
    ],
    "ayanamsa": "lahiri"
  }
}
```

## Accuracy and sources

- **Canonical texts** — *Muhurta Chintamani* (Ramadayalu Bhattacharya, ~1600 AD) and *Muhurta Martand* (Narayana, 17th c.). Modern compendia: B.V. Raman *Muhurta or Electional Astrology*; K.K. Pathak *Brihat Muhurta Bhusana*.
- **Panchang factors** — computed by our own panchang engine (`/v1/vedic/panchang/*`), the same source of truth.
- **Window scanning** — algorithm walks 15-minute slots inside `[start_date, end_date]`, scores each (0-100), returns the top-N sorted by `score desc`.
- **Algorithmic choices** — some rules (especially for `surgery`, `court-case`) come from narrow regional schools. We document the variant we picked and why in docs.
- **Status** — `marriage`, `vehicle-purchase`, `griha-pravesh`, `travel`, `business-start` are GREEN (cross-verified against Drik Panchang and ProKerala). `surgery`, `court-case`, `naming-ceremony`, `investment`, `property-purchase`, `education-start`, `engagement` are mostly YELLOW (single-source schools). Detailed breakdown in `docs/AUDIT-TRAIL.md`.

## Related

<CardGrid>
  <LinkCard title="Compatibility" href="/en/vedic/compatibility/" description="Match charts before marriage + Manglik" />
  <LinkCard title="Yogas" href="/en/vedic/yogas/" description="Raja, Dhana, Mahapurusha — combinations" />
  <LinkCard title="Doshas" href="/en/vedic/doshas/" description="Manglik, Kaal Sarp, Pitru — afflictions" />
  <LinkCard title="Credits" href="/en/credits/" description="Per-endpoint credit cost" />
  <LinkCard title="Accuracy" href="/en/accuracy/" description="How we verify calculations" />
  <LinkCard title="Authentication" href="/en/authentication/" description="X-Api-Key, sandbox keys" />
</CardGrid>