# Muhurta API — підбір сприятливих дат (ведична електив. астрологія)

Muhurta — це ведична **електив­на астрологія**: вибір сприятливого моменту для важливої події. API сканує кожен день у вашому вікні пошуку, оцінює його за **Панчангою на схід сонця** (Tithi · Vara · Nakshatra · Yoga · Karana) під конкретну активність і повертає top-N найкращих днів із поясненням.

## Як це працює

1. Оберіть **активність** (одну з 12 — список через `/muhurta/types`), **вікно пошуку** (до 90 днів) і **локацію** (схід сонця прив'язаний до координат)
2. API рахує Панчангу на схід сонця для кожного дня й оцінює його за класичними правилами активності (Muhurta Chintamani + B.V. Raman)
3. Відповідь — top-N днів, відсортованих за score, із Панчангою, під-вікном **Abhijit Muhurat** і факторами оцінки (`why`)

## Ендпоінти

| Ендпоінт | Метод | Кредити | Призначення |
|---|---|---|---|
| `/v1/muhurta/types` | GET | 0 | Каталог 12 активностей (ключ + санскрит + опис) |
| `/v1/vedic/muhurat/{activity}` | POST | Tier 3 | Скан вікна під одну активність → top-N днів (JSON) |
| `/v1/reports/muhurta` | POST | Tier 7 | Готовий звіт сприятливих дат — **PDF** (типово) або **HTML** (`?format=html`) |

## 12 активностей

`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`.

## Звіт

`POST /v1/reports/muhurta` повертає **стандартний A4-звіт** тим самим шляхом, що й решта `/v1/reports/*` — синхронний рендер у відповіді: PDF за замовчуванням, `?format=html` віддає HTML без рендера. Топ-рекомендація, ранжований список днів, Панчанга кожного дня, Abhijit Muhurat і фактори оцінки як обґрунтування. Підтримує white-label (логотип/кольори/шрифт) для ключів, прив'язаних до акаунта.

## Приклад

```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 повертає HTML напряму)
```

<Aside type="note">
Muhurta — дорадча модель за класичними текстами, не директива. Для surgery та медичних подій сучасне планування має пріоритет.
</Aside>