GCal API

Формат ответа

Большинство JSON-эндпоинтов:

// успех
{ "success": true, "data": { ... }, "message": "..."? }

// ошибка (часто HTTP 400)
{ "success": false, "error": "...", "error_code": "VALIDATION_ERROR", "error_details": ...? }

GET /health — исключение: { "status": "ok", "version": "..." } без envelope; поле version содержит build SHA. Версия всего приложения — 2.5.12 (SemVer), она отдельно показана в шапке QA-календаря.

Кэш API: заголовок Cache-Control: private, no-cache.

Ответы гzip-сжаты, если клиент шлёт Accept-Encoding: gzip (браузеры и большинство HTTP-клиентов делают это сами) — Content-Encoding: gzip в ответе, тело меньше в разы (~6× на /api/calendar-data). Ответы короче ~500 байт (напр. ошибки валидации) не сжимаются — оверхед gzip-заголовка не окупается.

Как передавать локацию

Для /api/calendar-data, /api/calendar-data/year, /api/calendar-data/next-event, /api/day-detail, /api/day-detail/astronomy и /api/day-detail/fasting-logic — два способа:

1. geonames_id — любая запись каталога city_catalog (~170k городов + несколько кастомных записей вроде Kosshy/Mayapur, см. ниже; результат /api/locations/catalog);
2. или lat + lon + timezone_offset вместе (рекомендуется внешним сайтам со своим списком городов).

Если передано и то, и другое — побеждает молча geonames_id. Невалидный/несуществующий geonames_id → VALIDATION_ERROR, не тихая подстановка другого города. Часть координатной тройки → VALIDATION_ERROR. Ничего не передано → geonames_id по умолчанию (Алматы, 1526384).

Все четыре эндпоинта календаря (calendar-data, calendar-data/year, calendar-data/next-event, day-detail) и day-detail/fasting-logic дополнительно принимают caturmasya_system=purnima|pratipat|ekadasi — какая из трёх традиций расчёта границ месяцев Чатурмасьи используется. По умолчанию — purnima — дефолт самой gaurabda из коробки, и он же совпадает с vaisnavacalendar.info (эталон, с которым сверяется satya-dharma). Неизвестное значение → VALIDATION_ERROR. Значение, которое реально применилось, всегда есть в ответе как поле caturmasya_system.

Те же эндпоинты принимают и fasting_note_style=classic|modern — формулировка заметок о посте при праздниках святых (GCDisplaySettings[42] в gaurabda): classic — «(Fast till noon for X, with feast tomorrow)», modern — «(Fast today for X)». По умолчанию — classic: на полной выборке из 202 городов × 2026 год против vaisnavacalendar.info под classic текст заметок совпадает с эталоном на 75.8% дат (3316/4375), под modern (дефолт самой gaurabda) — на 12.9% (561/4356). В отличие от caturmasya_system проверка на большой выборке подтвердила исходный результат — дефолт не менялся. Тот же контракт: неизвестное значение → VALIDATION_ERROR, применённое значение — в ответе рядом с caturmasya_system.

Диапазоны: год в year и параметрах-датах — 2..9998 (крайние годы исключены, поскольку расчёт использует соседние дни), month=1..12, lat -90..90, lon -180..180, timezone_offset=-14..14 часов от UTC (Алматы: 5). Нечисловые и неканонические значения не подменяются дефолтами, а возвращают VALIDATION_ERROR.

Объект location в ответе

Календарные эндпоинты (calendar-data, calendar-data/year, calendar-data/next-event, day-detail, day-detail/astronomy, day-detail/fasting-logic) возвращают в data.location резолвленную локацию — не то, что было передано в запросе, а то, что реально использовалось для расчёта:

Календарные эндпоинты

GET /api/calendar-data

Сетка месяца + события.

data (без compact): location, year, month, gaurabda_year, days{}, ekadashi_events[], events[], caturmasya[], payload_version, caturmasya_system, fasting_note_style, event_categories.

GET /api/calendar-data?geonames_id=1526384&year=2026&month=9
GET /api/calendar-data?geonames_id=1526384&year=2026&month=9&compact=1  # без grid-only days/ekadashi_events/caturmasya

GET /api/calendar-data/year

events[] за весь год одним запросом — без сетки (days{}) и без месячного фильтра. Отдельного расчёта не требует: год и так считается и кэшируется целиком (gcal_cache.get_year), этот эндпоинт просто не фильтрует его по месяцу.

data: location, year, events[], payload_version, caturmasya_system, fasting_note_style, event_categories — форма ответа всегда компактная, отдельного compact-параметра нет.

GET /api/calendar-data/year?geonames_id=1526384&year=2026  # events[] за весь 2026 год, caturmasya_system=purnima + fasting_note_style=classic (дефолты)
GET /api/calendar-data/year?geonames_id=1526384&year=2026&caturmasya_system=pratipat
GET /api/calendar-data/year?geonames_id=1526384&year=2026&fasting_note_style=modern
GET /api/calendar-data/year?geonames_id=1526384&year=2026&event_categories=4  # только ISKCON's historical events среди festival

GET /api/calendar-data/next-event

Первое подходящее событие с датой date >= from. Если его нет в оставшейся части года, автоматически проверяется следующий календарный год; дальше поиск не продолжается. Использует тот же годовой кэш, но не строит и не сериализует полный events[].

data: location, from, event (обычное публичное событие с добавленным date либо null), payload_version, caturmasya_system, fasting_note_style, event_categories.

GET /api/calendar-data/next-event?geonames_id=1526384&from=2026-07-31&event_kinds=ekadashi,mahadvadashi

{
  "success": true,
  "data": {
    "location": {
      "geonames_id": 1526384,
      "coordinate_source": "geonames",
      "lat": 43.25249,
      "lon": 76.9115,
      "alt": 783.0,
      "timezone_offset": 5.0,
      "name": "Алматы",
      "country": "KZ",
      "region": "Алматы",
      "tzname": "Asia/Almaty"
    },
    "from": "2026-07-31",
    "event": {
      "date": "2026-08-09",
      "event_code": "EKADASHI",
      "event_kind": "ekadashi",
      "text": "Fasting for Kamika Ekadasi"
    },
    "payload_version": "v17.2",
    "caturmasya_system": "purnima",
    "fasting_note_style": "classic",
  }
}

GET /api/day-detail

Детали одного дня (времена, сегменты титхи, накшатра, йога, раши Солнца и Луны, экадаши/парана, sankranti).

Расширенный панчанга: nakshatra_elapsed_percent (0..<100), nakshatra_pada (1..4), yoga/yoga_name (0..26), sun_rasi/sun_rasi_name и moon_rasi/moon_rasi_name (0..11). Значения относятся к восходу дня. Эти поля не добавляются в compact-ответы и /api/calendar-data/year.

date_timezone_offset — фактическое дневное UTC-смещение на выбранную дату с учётом DST (режим в местный полдень, используемый суточным расчётом Gaurabda). Это не замена IANA-зоне для каждого момента: в ночь перехода смещение в 00:00 может отличаться, поэтому готовые JD форматируются по tzname. В ekadashi{} явно отдаются ekadashi_date и fast_day; у постового дня parana{} содержит date, time1, time2. Поэтому клиенту не нужно выводить относительное «завтра» или самостоятельно вычислять дату перенесённого поста/паранама.

Структурные признаки: is_ksaya, ksaya_tithi (1..30 или null), vriddhi_day (1, 2 или null), masa_start/masa_end. Они формируются из соседних дней, уже рассчитанных GCal, без включения английских display-заметок. is_ksaya стоит на дне после пропущенной титхи; vriddhi_day различает первый и второй восход повторённой титхи. Те же поля есть у дня в полном days{}; в compact и годовой endpoint не входят.

moonrise_time/moonset_time — местное HH:MM либо null, если события нет внутри этих гражданских суток. Расчёт точечный, топоцентрический, для центра диска Луны на горизонте 0° без рефракции; дорогие годовые ключи GCDisplaySettings[4]/[5] не включаются. Нативное ядро включается только после self-check с Python-путём, а результат дня лениво кэшируется в ограниченной памяти worker'а. На независимой сверке 1825 городо-дней со Swiss Ephemeris совпадение наличия событий — 100%, медиана времени около 2.8 сек, максимум 18.7 сек.

arunodaya_offset_minutes показывает фактический интервал до восхода; night_muhurta_minutes — одну пятнадцатую предыдущей фактической ночи. При fixed-варианте первое поле равно 96 минутам, а второе остаётся сезонным справочным значением; при temporal-варианте первое равно удвоенному второму.

GET /api/day-detail?geonames_id=1526384&date=2026-09-04

GET /api/day-detail/astronomy

Ленивая астрономическая часть объединённой модалки дня. Принимает обязательные date=YYYY-MM-DD и локацию. Расширенный набор (карана, pāda, мухурты, транзиты) — только с research=1&extended_panchanga=1; см. docs/research/internal-research-api.md. Имеет отдельный SQLite/LRU-кэш и не меняет годовой payload_version.

• civil_day_hours — реальная длина гражданской даты (24, на переходе DST 23/25 часов); day_length_hours/night_length_hours, тропические долготы Солнца/Луны и tithi_angle_deg в Arunodaya;
• ayanamsha_arunodaya_deg — поворот кольца сидерических раши; *_longitude_day_start_deg/*_longitude_day_end_deg — положения в местные 00:00 и следующие 00:00 для внутренних дуг движения (23/25-часовые DST-сутки учитываются);
• tithi_segments/nakshatra_segments — сводка гражданских суток; массивы *_chart_segments для титхи, накшатр, точных pāda, каран, йог и раши покрывают общую ось графика -3…+27 часов;
• muhurta_segments — 45 отрезков: предыдущая ночь, день и следующая ночь по 15; altitude_curve — высоты Солнца/Луны с шагом 15 минут, с локальными date/time каждой точки для корректной пропущенной/повторённой DST-часовой метки;
• sun_transit_*/moon_transit_* — уточнённые верхние кульминации.

Соглашения расчёта: титхи/карана используют геоцентрическую разность долгот центров Луны и Солнца; накшатра, pāda и rāśi Луны — геоцентрическую долготу центра Луны с GCal Lahiri ayanāṃśa; нитья-йога — сумму долгот центров с двойной ayanāṃśa. Край диска, горизонт и рефракция для этих величин не участвуют. В default-режиме центр Солнца находится на −0.833° потому, что выбран верхний край (+16′) и фиксированная рефракция (+34′); альтернативы задаются независимыми ключами выше. Moonrise/moonset — топоцентрический центр Луны на геометрическом горизонте 0° без рефракции. Высоты на графике также геометрические, без рефракции.

На UI участки кривых выше горизонта сплошные, ниже — пунктирные. События Солнца подписаны сверху, события Луны/титхи/смены раши — снизу.

GET /api/day-detail/astronomy?geonames_id=1526384&date=2026-09-04

GET /api/day-detail/fasting-logic

Пояснение выбора дня поста экадаши для QA-UI (кнопка «Почему этот день?» в модалке дня). Читает уже кэшированный год, астрономию не пересчитывает, payload_version не меняет. 404, если дата не из окна календарной экадаши / дня поста / паранам.

В steps[] только сработавшие проверки GCal (MahadvadasiCalc → EkadasiCalc → окно паранам), без перечня отпавших соседних типов. sources[] — цитаты Hari-bhakti-vilāsa по сработавшему типу.

GET /api/day-detail/fasting-logic?geonames_id=1526384&date=2026-08-24

GET /api/panchanga-timeline (internal)

Внутренний/отладочный эндпоинт (x-internal в OpenAPI). QA UI и satya-dharma его не вызывают; та же логика используется внутри day-detail/astronomy. Точные по модели GCal моменты начала титхи, санкранти, накшатры и йоги в полуоткрытом интервале местных гражданских дат [start, end). Расчёт ленивый и не изменяет годовой/compact payload.

data: location, start, end, types, events[]. С research=1 дополнительно metadata расчёта (см. internal-research-api). Общие поля события: event_kind, at_utc, local_date, local_time. У tithi_start: tithi_number (1..30), tithi_name; у sankranti и conjunction: rasi (0..11), rasi_name; у nakshatra_start: nakshatra/nakshatra_name (0..26); у yoga_start: yoga/yoga_name (0..26).

GET /api/panchanga-timeline?geonames_id=1526384&start=2026-04-01&end=2026-05-01
GET /api/panchanga-timeline?geonames_id=1526384&start=2026-04-01&end=2026-05-01&types=sankranti
GET /api/panchanga-timeline?geonames_id=1526384&start=2026-04-01&end=2026-05-01&types=nakshatra,yoga
GET /api/panchanga-timeline?geonames_id=1526384&start=2026-04-01&end=2026-05-01&types=conjunction

GET /api/research/arunodaya-scales (internal)

Внутренний/исследовательский эндпоинт (x-internal в OpenAPI). Только с research=1 (иначе 404). QA-графики трёх шкал aruṇodaya за год; satya-dharma не вызывает. Не меняет year-payload. Подробности — docs/research/internal-research-api.md.

data: location, year, days[] с часами от местной полуночи (sunrise_hour, arunodaya_96_hour, arunodaya_215_hour, arunodaya_1212_hour, solar6_hour; null в полярные сутки). Плюс metadata расчёта. Выбор arunodaya_definition на состав рядов не влияет — всегда все три шкалы.

GET /api/research/arunodaya-scales?geonames_id=1526384&year=2026&research=1

События events[]

Каждый элемент: { date?, event_code, event_kind, text, event_category?, event_category_name?, fasttype?, fastsubject? }.

• event_kind: ekadashi | mahadvadashi | parana | festival | caturmasya | sankranti | other
• event_code: стабильный id в рамках версии gaurabda (SPEC_*, EVT_<index>, …)
• event_category/event_category_name — только у event_kind == "festival" (у остальных kind'ов поле отсутствует, не null — у них этой классификации в gaurabda просто нет). event_category — число 0..6:

  0	Appearance days of the Lord
  1	Events in the pastimes of the Lord
  2	Appearance/disappearance of recent acaryas
  3	Appearance/disappearance of Mahaprabhu's associates and other acaryas
  4	ISKCON's historical events
  5	Bengal-specific holidays
  6	Personal events

event_categories=0,4 (все три эндпоинта календаря) — список чисел 0..6 через запятую, оставляет в events[] только festival-события этих категорий. Остальные event_kind (экадаши, парана, Чатурмасья, санкранти...) фильтр не трогает — у них категории нет, они приходят всегда. Параметр не передан — фильтр не применяется. Неизвестное число → VALIDATION_ERROR. Применённый фильтр отражён в ответе как event_categories (null, если не передавали).

Справочник локаций

GeoNames — подход

Единственный справочник локаций — city_catalog (~170k городов, сид из data/cities_geonames.csv при первом старте БД, плюс несколько записей вне GeoNames — Kosshy/Mayapur, см. schema.CUSTOM_CITIES). Отдельного куррированного справочника с внутренним id больше нет — всё адресуется по geonames_id.

Типичный поток для UI / сайта:

1. GET /api/locations/catalog?search=Алматы — найти город (поля: id каталога — служебный, не для адресации, name, name_ru, lat, lon, timezone_offset, country, geonames_id, region, population, tzname — IANA-зона, напр. Asia/Almaty; результаты отсортированы по населению, крупные города — в начале списка); timezone_offset в этом ответе — «стандартный» (не-DST) числовой offset, как и раньше — но сам расчёт календаря (events[]/days{} из /api/calendar-data) DST-осведомлён: для городов с переходом на летнее время восход/закат/титхи/накшатра/санкранти считаются по фактическому смещению на каждую дату (по tzname из каталога), не по одному фиксированному числу на весь год;
2. дальше считать календарь по geonames_id из найденной записи — ничего никуда не пишется: GET /api/calendar-data?geonames_id=<geonames_id>&...;
3. либо, если своих координат у сайта уже достаточно, — сразу lat/lon/timezone_offset без обращения к каталогу вовсе.

# поиск (компактно, для автокомплита)
curl -sS 'BASE/api/locations/catalog?search=Almaty&limit=5&compact=1'

# сразу расчёт по geonames_id из результата поиска, компактный ответ
curl -sS 'BASE/api/calendar-data?geonames_id=1526384&year=2026&month=9&compact=1'

# ближайшая Экадаши/Махадвадаши для hero
curl -sS 'BASE/api/calendar-data/next-event?geonames_id=1526384&from=2026-07-31&event_kinds=ekadashi,mahadvadashi'

Служебное

APP_VERSION → 2.5.12 (SemVer, показан в шапке QA-календаря)
GET /health → { "status": "ok", "version": "..." }  # build GIT_SHA
GET /openapi.json → OpenAPI 3.1, JSON
GET /       → HTML QA-календарь
GET /docs   → эта страница