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

Модель, яка вгадує назву поля, отримує або 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	ні

Обережно

city нічого не геокодує. Це поле для підпису у вашому інтерфейсі, і воно ніколи не замінює координати.

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

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

{ "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, і сервер візьме зсув із бази часових поясів, разом із літнім часом.

{ "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 можуть бути в різних зонах.

Заувага

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

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.

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

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

Далі

• Типові помилки
• Підводні камені