# Muhurta API — auspicious date finder (Vedic electional astrology)

Muhurta is Vedic **electional astrology** — choosing an auspicious moment for an important event. The API scans every day in your search window, scores it by the **sunrise Panchang** (Tithi · Vara · Nakshatra · Yoga · Karana) for a specific activity, and returns the top-N best days with the reasoning.

## How it works

1. Pick an **activity** (one of 12 — list via `/muhurta/types`), a **search window** (up to 90 days), and a **location** (sunrise is location-anchored)
2. The API computes the sunrise Panchang for each day and scores it against the activity's classical rules (Muhurta Chintamani + B.V. Raman)
3. The response is the top-N days sorted by score, with Panchang, the **Abhijit Muhurat** sub-window, and the scoring factors (`why`)

## Endpoints

| Endpoint | Method | Credits | Purpose |
|---|---|---|---|
| `/v1/muhurta/types` | GET | 0 | Catalogue of the 12 activities (key + Sanskrit + description) |
| `/v1/vedic/muhurat/{activity}` | POST | Tier 3 | Window scan for one activity → top-N days (JSON) |
| `/v1/reports/muhurta` | POST | Tier 7 | Ready-made auspicious-dates report — **PDF** (default) or **HTML** (`?format=html`) |

## The 12 activities

`marriage` (Vivah) · `vehicle-purchase` (Vahana) · `business-start` (Vyapara) · `travel` (Yatra) · `naming-ceremony` (Namkaran) · `surgery` (Shastrakarma) · `education-start` (Vidyarambha) · `investment` (Dhana Sthapana) · `property-purchase` (Griha Pravesh) · `journey-long` · `name-change` · `general-auspicious`.

## The report

`POST /v1/reports/muhurta` returns a **standard A4 report** via the same path as the rest of `/v1/reports/*` — rendered synchronously in the response: PDF by default, `?format=html` returns HTML without rendering. Top recommendation, a ranked list of days, each day's Panchang, Abhijit Muhurat, and the scoring factors as the rationale. White-label (logo/colours/font) is supported for account-bound keys.

## Example

```bash
curl -X POST https://api.astroway.info/v1/reports/muhurta \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "activity": "marriage", "search_window_start": "2026-07-01",
        "search_window_end": "2026-07-31", "latitude": 28.61,
        "longitude": 77.21, "timezoneOffset": 5.5, "topN": 5 }'
# → { "url": "https://api.astroway.info/reports/…-muhurta.pdf", "page_count": 2, "expires_at": "…" }
# (?format=html returns HTML directly)
```

<Aside type="note">
Muhurta is an advisory model from classical texts, not a directive. For surgery and medical events, modern scheduling takes precedence.
</Aside>