# API істинного сонячного часу

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

## Ендпоінт

`POST /v1/chinese/true-solar-time`

- Operation ID: `chinese/true-solar-time`
- Вартість: 10 кредитів (тариф 1)
- Типова латентність: 55 мс, заміряно на проді
- Канонічна сторінка: https://api.astroway.info/astrology-api/true-solar-time/

## Що обчислює

Істинний сонячний час це годинний кут видимого Сонця на довготі народження, зсунутий на півдоби, взятий зі швейцарських ефемерид як видиме пряме сходження проти грінвіцького середнього зоряного часу. Він розкладається на два доданки, які повідомляються окремо. Меридіанний доданок це відстань місця від меридіана свого поясу, чотири хвилини на градус, і саме він великий: Китай живе за одним зміщенням від Кашгара до Харбіна, тож народження в Сіньцзяні відстоїть від власного годинника майже на три години. Рівняння часу це власне річне коливання Сонця, до приблизно шістнадцяти хвилин в обидва боки, і саме його альманахові таблиці зазвичай опускають. Відповідь також повідомляє, чи перетнула поправка північ, бо це зсуває денний стовп, а не саму лише годину.

## Коли використовувати

Беріть щоразу, коли карта залежить від подвійної години, а місце народження далеке від меридіана свого поясу: годинні стовпи BaZi, годинні палаци Zi Wei, будь-яке китайське читання для народження в західному Китаї, у широкому поясі на кшталт Іспанії чи Аргентини, або там, де межа поясу колоніальної доби лежить далеко від меридіана. Він також стоїть окремо як утиліта для сонячного годинника і для звіряння друкованого альманаху з годинниковим часом. Усередині нашої ж поверхні BaZi та сама поправка доступна прапорцем trueSolarTime, тож викликати цей ендпоінт і пересилати результат зазвичай не треба.

## Параметри запиту

| Parameter | Type | Required | Description |
|---|---|---|---|
| `date` | string (YYYY-MM-DD) | yes | Local calendar date at birth. |
| `time` | string (HH:MM:SS) | yes | Local clock time at birth. |
| `timezoneOffset` | number (hours) | yes | The offset the clock was actually running on. A 1988 Beijing birth ran on +9 under summer time, and no arithmetic here recovers that from the date. |
| `longitude` | number | yes | Birth longitude in decimal degrees, east positive. |

## Приклад запиту

```bash
curl -X POST https://api.astroway.info/v1/chinese/true-solar-time \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-05-15",
    "time": "14:30:00",
    "timezoneOffset": 8,
    "longitude": 87.6
  }'
```

## Приклад відповіді

```json
{
  "ok": true,
  "data": {
    "clockTime": "14:30:00",
    "trueSolarTime": "12:24:06",
    "totalCorrectionMinutes": -125.89,
    "longitudeCorrectionMinutes": -129.6,
    "equationOfTimeMinutes": 3.71,
    "dayShift": 0,
    "date": "1990-05-15"
  }
}
```

## Нотатки

Поправка сягає дня і години і навмисно не сягає року і місяця. Lichun і 節 це світові миті, і показання сонячного годинника не мають стосунку до того, коли Сонце перетинає 315 градусів. Застосування поправки до межі року це справжня і поширена помилка: народження через сімнадцять хвилин після Lichun вона віддає попереднім роком і чотирма невірними стовпами. Рівняння часу пришпилене до чотирьох опублікованих точок повороту річної кривої і до чотирьох її нулів.

## Пов’язані техніки

- https://api.astroway.info/astrology-api/bazi-chart/
- https://api.astroway.info/astrology-api/chinese-zodiac-compatibility/
- https://api.astroway.info/astrology-api/natal-chart/

---

Повна машиночитана специфікація: https://api.astroway.info/v1/openapi.json
Інструкції для агента: https://api.astroway.info/AGENTS.md