# Формати полів

Модель, яка вгадує назву поля, отримує або `400`, або, що гірше, впевнену відповідь про іншу карту. Нижче точний контракт.

## Тіло карткового запиту

| Поле | Тип і формат | Обов'язкове |
|---|---|---|
| `date` | `YYYY-MM-DD`, і це має бути реальний день календаря | так |
| `time` | `HH:mm:ss` | так, або `timeUnknown: true` |
| `timezoneOffset` | число, години від UTC, напр. `5.75` | ні, типово `0` (UTC) |
| `timezone` | назва зони IANA, напр. `Europe/Kyiv`, або `auto` | ні, а коли надіслано, замінює `timezoneOffset` |
| `latitude` | десяткові градуси, північ додатна | так |
| `longitude` | десяткові градуси, схід додатний | так |
| `houseSystem` | одна літера, типово `P` | ні |
| `city` | рядок, лише підпис | ні |
| `zodiacType` | `tropical` або `sidereal` | ні |

<Aside type="caution">
`city` нічого не геокодує. Це поле для підпису у вашому інтерфейсі, і воно **ніколи** не замінює координати.
</Aside>

## Короткі написання відхиляються

`lat`, `lon`, `lng`, `long`, `tz`, `tzOffset`, `utcOffset`, `gmtOffset`, `timeZone`, `time_zone` повертають `400 INVALID_FIELD` з назвою правильного поля:

```json
{ "error": { "code": "INVALID_FIELD",
  "message": "Unsupported field \"tz\". Rename it to \"timezoneOffset\" (numeric hours from UTC, e.g. 5.75; a zone name goes in timezone)." } }
```

Регістр і роздільники значення не мають: `TZ_Offset` і `tzoffset` відхиляються так само. Повідомляються **всі** знайдені поля одразу, а не перше, щоб виправити можна було за один раз.

Причина сувора: до цієї перевірки поле, яке API не читав, мовчки давало зсув `0`, і відповідь була впевненою картою для UTC. Три години зсуву це приблизно 45° асцендента, тобто інший знак, що сходить, і жодного попередження.

## `timezone`: назва зони замість зсуву

Зсув має бути тим, який тримали годинники **саме тієї дати**, і вручну його легко вказати хибно: Київ у травні 1990 року жив за московським літнім часом, UTC+4, а не +3. Надішліть `timezone`, і сервер візьме зсув із бази часових поясів, разом із літнім часом.

```json
{ "date": "1990-05-15", "time": "14:30:00", "timezone": "Europe/Kyiv",
  "latitude": 50.45, "longitude": 30.52 }
```

- `auto` визначає зону за `latitude` і `longitude`. Біля кордону назва точніша.
- Якщо `timezone` і `timezoneOffset` прийшли разом, діє `timezone`. `input.timezoneOffset` у відповіді показує зсув, який було використано.
- Час, що був двічі (коли годинники переводили назад), береться за першим разом. Час, якого не було (коли переводили вперед), отримує зсув, що діяв до переведення.
- Без `time` (лише дата або `timeUnknown: true`) зона читається на місцевий полудень.
- Відхиляються з `400 INVALID_FIELD`: порожнє значення, абревіатури на кшталт `EST` чи `PST`, зсув, записаний текстом, як `+03:00`, назви, яких немає в базі, і `auto` без координат. `UTC` і `GMT` приймаються.
- Кожен об'єкт розбирається окремо, тож `chart1` і `chart2` можуть бути в різних зонах.

<Aside type="note">
До 1970 року база часових поясів надійна не для кожного місця: Амстердам у червні 1930 року повертається як +1, хоча годинники показували +0:20. Якщо місцевий час того народження відомий, надішліть `timezoneOffset`.
</Aside>

## `houseSystem`: літера, не назва

Приймаються рівно ці 25 кодів Swiss Ephemeris:

`P` `K` `R` `C` `E` `W` `B` `M` `O` `A` `T` `V` `D` `F` `G` `H` `I` `i` `L` `N` `Q` `S` `U` `X` `Y`

Регістр значущий: `I` це Sunshine за Макранскі, `i` за Трайндлем. Назва системи (`"Placidus"`, `"Koch"`) повертає `400`. Раніше вона працювала випадково, бо рушій читає з рядка тільки першу літеру, і з тієї ж причини `"Zodiac"` мовчки давав Placidus.

## Невідомий час народження

Замість вигаданого полудня передавайте `timeUnknown: true` і не передавайте `time`. Тоді `houses`, `houseAspects`, `chartSect` і `siderealTime` приходять `null`, а не вигаданими. Подробиці: [Конвенції API](/api-conventions/#невідомий-час-народження).

## Невідомі ключі не відхиляються

Тіло приймає зайві поля мовчки: незнайомий ключ просто ігнорується. Тому помилка в назві поля, якої немає в списку відхилень вище, не дасть про себе знати. Звіряйтеся зі специфікацією: [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json).

## Далі

- [Типові помилки](/agent-setup/mistakes/)
- [Підводні камені](/agent-setup/gotchas/)