# Індуський календар - свята, врати, місячні місяці, регіональні календарі, ICS

Шість ендпойнтів, які перетворюють [панчанг](/vedic/panchang/) на календар. Жодна дата не береться з таблиці: кожне свято це правило (місячний місяць, тітхі й частина доби, якій належить обряд, або вхід Сонця в знак), а дату обчислено для місця, яке ви надіслали. Нью-Йорк отримує дні за своїми сходом і заходом Сонця, і у 2025 році це на день раніше, ніж у Нью-Делі, для 48 свят.

Кожен запис повертає правило, за яким його датовано, джерело і те, як обрано день, тож розбіжність із друкованим альманахом можна простежити до умови, що її спричинила.

## Ендпойнти

| Ендпойнт | Кредити | Що повертає |
|---|---|---|
| `POST /v1/vedic/calendar/festivals` | 100 | Близько 55 свят року, кожне з правилом, джерелом, вікном тітхі й місяцем |
| `POST /v1/vedic/calendar/vrats` | 100 | Екадаші (смарта й вайшнава, з параною), Прадош, Санкашті, Пурніма, Амавасья, Масік Шіваратрі |
| `POST /v1/vedic/calendar/months` | 50 | Місячні місяці з адхікою й кшаєю, санкранті, ери Шака і Вікрам |
| `POST /v1/vedic/calendar/regional/months` | 50 | Межі місяців тамільського, малаялам, бенгальського, гуджаратського чи маратхі року |
| `POST /v1/vedic/calendar/regional/date` | 20 | Одна григоріанська дата в регіональному календарі |
| `GET /v1/vedic/calendar/ics` | 100 | Свята й врати року як файл iCalendar |

Усі приймають `latitude`, `longitude` і `timezone` (назву IANA, наприклад `Asia/Kolkata`, або `auto`, типово, щоб визначити її за координатами). Пояс застосовується день за днем, тож літній час за кордоном враховано. Замість нього можна надіслати сталий `timezoneOffset`. Широти понад 66 градусів відхиляються: там Сонце деяких днів не сходить, а індуська доба, що триває від сходу до сходу, не має початку. `ayanamsaId` (або `ayanamsa` за назвою) задає сидеричний зодіак для санкранті й назв місяців; типово Лахірі.

```bash
curl https://api.astroway.info/v1/vedic/calendar/festivals \
  -H "X-Api-Key: $ASTROWAY_KEY" -H "Content-Type: application/json" \
  -d '{ "year": 2026, "latitude": 28.6139, "longitude": 77.209, "timezone": "Asia/Kolkata", "festivals": ["diwali"] }'
```

## Як датується свято

Місячне свято називає місяць, тітхі й калу, частину доби, якій належить обряд. Тітхі святкують того дня, коли вона діє під час цієї кали:

| Кала | Вікно |
|---|---|
| sunrise | мить сходу Сонця (удая-тітхі) |
| arunodaya | 96 хвилин (4 гхаті) до сходу |
| pratahkala, madhyahna, aparahna, sayahna | 1-ша, 3-тя, 4-та і 5-та п'ятина світлового дня |
| purvahna | перша половина світлового дня |
| pradosha | перша п'ятина ночі (три мухурти після заходу) |
| purvaratri | перша половина ночі |
| nishita | восьма з п'ятнадцяти мухурт ночі |
| moonrise | мить сходу Місяця |

`basis` каже, як обрано день: `vyapti`, коли тітхі застала калу одного дня, `vriddhi`, коли двох, і вибір зробило правило (перший, другий або той, що вкрито довше), `kshaya`, коли жодного, і вибір зробив запасний варіант правила. Ракша Бандхан і Холіка Дахан також виключають Бхадру (карану Вішті). Ганга Дашахару святкують в адхіка-місяці, коли рік має Адхіка Джйештху, як 2026-го.

Сонячні свята йдуть за регіональним правилом свого календаря: Макар Санкранті й Тай Понгал у день входу, якщо він до заходу Сонця, Вішу на перший схід після входу в Мешу, Похела Бойшакх за бенгальським правилом. Онам це день, коли на схід діє Тірувонам (Шравана) у місяці Чінгам, і другий такий, якщо в Чінгамі їх два.

`tradition` вирішує два свята, які смарта і вайшнави рахують по-різному: `smarta` (типово) читає Рама Навамі опівдні, а Джанмаштамі опівночі, `vaishnava` читає обидва на схід, ніколи не поєднані з попередньою тітхі. У Нью-Делі 2025 року це переносить Джанмаштамі з 15 на 16 серпня.

Кожен запис несе обидві назви місяця: аманта (від молодика до молодика, Південна і Західна Індія) і пурніманта (від повні до повні, Північна Індія). Вони різняться лише в Крішна-пакші: Дівалі 2026 припадає на амантський Ашвін і пурнімантський Картік.

## Врати

| Тип | Правило |
|---|---|
| `ekadashi` | див. нижче |
| `pradosh` | Трайодаші у прадошу, з двох днів той, що вкрито довше; назва за днем тижня (Сома, Бхаума, Шані Прадош) |
| `sankashti` | Крішна Чатурті на схід Місяця; схід Місяця повертається; назва за пурнімантським місяцем |
| `masik-shivaratri` | Крішна Чатурдаші в нішіту |
| `purnima` | врата Пурніми (Пурніма діє опівдні) і день омовіння (Пурніма на схід), які можуть різнитися на день |
| `amavasya` | Дарша Амавасья (діє пополудні, у час шраддхи) і день омовіння (на схід) |

**Екадаші.** День смарта той, коли Екадаші діє на схід. Коли вона застає два сходи, перший, якщо його не торкнулася Дашамі в арунодаю, інакше всі постять другого. Коли потім Двадаші не застає жодного сходу, парана випала б на Трайодаші, тож смарта постять напередодні. Коли Екадаші не застає жодного сходу, день, коли вона починається. День вайшнавів відкидає Дашамі-віддху: Дашамі в арунодаю переносить піст на день; другий схід в Екадаші це день Гауна; Двадаші на два сходи (Ванджулі) переносить піст на перший з них. `observance` дорівнює `both`, коли дні збігаються, інакше є запис для `smarta` і запис для `vaishnava`.

`parana` це вікно наступного ранку, щоб перервати піст: ніколи в Харі Васару (першу чверть Двадаші), у межах Двадаші, бажано в пратахкалу; коли Харі Васара триває довше за пратахкалу, після мадхьяхни до кінця апарахни; коли Двадаші скінчилася до сходу, у пратахкалу. Разом повертаються `hariVasaraEnds` і `dwadashiEnds`.

## Місячні місяці

`/vedic/calendar/months` перелічує місяці, що торкаються року. Місяць триває від молодика до молодика й має назву сидеричного знака, у якому Сонце на початковому молодику, плюс один: Сонце в Міні дає Чайтру. Місяць без санкранті всередині це адхіка, він бере назву наступного; місяць із двома це кшая, і `kshayaOf` називає місяць, який він поглинув. 2026 рік має Адхіка Джйештху з 17 травня до 15 червня. Відповідь також несе дванадцять моментів санкранті й ери: Шака (1948 від Чайтри 2026), Вікрам Самват від Чайтри (2083) і від Картіки, як рахують у Гуджараті, та назву шістдесятирічного самватсари (Парабхава).

## Регіональні календарі

`calendar` один із п'яти.

| Календар | Початок місяця | Рік |
|---|---|---|
| `tamil` | санкранті до заходу Сонця: того дня; після: наступного | назва самватсари, від Чіттірая |
| `malayalam` | санкранті в перші три п'ятини світлового дня: того дня; пізніше: наступного | ера Коллам, від Чінгама |
| `bengali` | санкранті між сходом і північчю: наступного дня; після півночі: ще через день | Бангабда, від Бойшакха |
| `gujarati` | амантський місячний місяць, Суд і Вад | Вікрам Самват від Картіки (день після Дівалі) |
| `marathi` | амантський місячний місяць | Шака від Чайтри (Гуді Падва) |

`/regional/months` дає перший і останній цивільний день кожного місяця, тривалість, санкранті або молодики й рік. `/regional/date` перетворює одну дату: для сонячних календарів місяць і його день, для місячно-сонячних місяць і тітхі на місцевий схід.

```bash
curl https://api.astroway.info/v1/vedic/calendar/regional/date \
  -H "X-Api-Key: $ASTROWAY_KEY" -H "Content-Type: application/json" \
  -d '{ "calendar": "malayalam", "date": "2026-08-17", "latitude": 9.9312, "longitude": 76.2673, "timezone": "Asia/Kolkata" }'
```

## ICS-стрічка

`GET /v1/vedic/calendar/ics` повертає `text/calendar`: одну подію на весь день на кожне свято й врату, з правилом, вікном тітхі, параною й джерелом в описі та UID, який не змінюється між викликами. Параметри запиту: `year`, `latitude`, `longitude`, `timezone`, `include` (`festivals`, `vrats` або окремі типи врат, наприклад `ekadashi`, через кому; типово `festivals,vrats`) і `tradition`.

**Caution:**
Ключ передається в заголовку `X-Api-Key`, як на кожному ендпойнті, а календарні застосунки заголовків не надсилають. Завантажуйте файл на своєму сервері (раз на рік для місця досить) і віддавайте його користувачам звідти. Ніколи не кладіть ключ в URL.

```bash
curl "https://api.astroway.info/v1/vedic/calendar/ics?year=2026&latitude=28.6139&longitude=77.209&timezone=Asia/Kolkata&include=festivals,ekadashi" \
  -H "X-Api-Key: $ASTROWAY_KEY" -o hindu-2026.ics
```

## Як це перевірено

Проти drikpanchang.com за 2025 і 2026 роки: 323 з 325 дат свят для Нью-Делі, Ченнаї й Нью-Йорка збігаються, а на контрольній вибірці, якою не налаштовувалося жодне правило (Нью-Делі 2024 і 2027, Лондон 2026, Мумбаї 2025), 204 з 214. Кожна розбіжність це свято, чия тітхі застає калу двох днів, де альманахи вирішують по-різному (відомий випадок Дівалі 2024: 31 жовтня чи 1 листопада). Дні Екадаші для смарта і вайшнавів у Нью-Делі 2024-2027 збігаються всі, крім одного; вікна парани 2026 року в межах хвилини. Прадош, Санкашті, Масік Шіваратрі, Пурніма й Амавасья для Нью-Делі 2025 і 2026 збігаються всі.

**Note:**
Моменти санкранті тут на 5-8 хвилин раніші, ніж у drikpanchang на тій самій аянамші Лахірі, а кінці тітхі приблизно на хвилину пізніші. Початок регіонального місяця чи свято, чия умова припадає в ці хвилини до межі, можуть вийти на день інакше.