Форматы полей

• URL — базовый адрес https://api.occultapi.com, затем маршрут ровно в том виде, как он указан, со слешем в конце.
  Правильно: /api/astro/tithi/, /api/astro/dasha/vimshottari/, /api/festivals/.
  Неправильно: /api/astro/tithi, /astro/tithi/, /api/astro/Tithi/.
• Аутентификация — ключ в заголовке X-API-Key и Content-Type: application/json в каждом POST-запросе.
• Метод — POST с телом в JSON. Немногие GET-запросы (поиск места, значение аянамши, таблицы шалака и данные о стихийных бедствиях) принимают входные данные, если они нужны, в параметрах строки запроса.
  Правильно: POST /api/astro/panchanga/ с телом в JSON; GET /api/astro/geocode/?address=Jaipur.

• date_time — ISO 8601 со смещением от UTC или с Z в конце; это момент, на который делается расчёт (для натальной карты — момент рождения).
  Правильно: "1990-08-15T10:30:00+05:30", "2026-09-01T00:30:00Z".
  Неправильно: "1990-08-15 10:30:00" (без смещения большинство эндпоинтов считают это время UTC+05:30, а некоторые — UTC), "15/08/1990 10:30 AM".
• datetime — то же значение под другим именем. /api/astro/chart/, маршруты дробных карт и /api/astro/planet-positions/ требуют именно такого написания; маршруты даш принимают оба варианта.
• date и time — только в /api/astro/date_time/: он принимает местное время по часам и координаты и возвращает метку времени с правильным смещением для этой даты.
  Правильно: "1990-08-15" и "10:30:00".
• year, month, day — обычные целые числа там, где эндпоинт их просит (нумерология, календари, поиск событий за год).
  Правильно: 1990, 8, 15.

• latitude / longitude — десятичные градусы. Север и восток — положительные значения, юг и запад — отрицательные.
  Правильно: 26.9124, 75.7873 (Джайпур); 40.7128, -74.006 (Нью-Йорк).
  Неправильно: "26°54′N", строки или 74.006 для Нью-Йорка (без минуса он переедет в Китай).
• timezone_as_float — смещение от UTC в часах, число от -12 до 14, действовавшее в этом месте на эту дату (с учётом летнего времени).
  Правильно: 5.5 (Индия), -4 (Нью-Йорк летом), 5.75 (Непал).
  Неправильно: "+05:30", "Asia/Kolkata", "IST".
• В некоторых эндпоинтах то же смещение называется иначе: timezone (например, /api/astro/dosha/ и /api/astro/strength/), tz (/api/astro/transit/) и time_zone (/api/astro/celestial/). Отправляйте то имя, которое указано у эндпоинта.

• ayanamsa (сидерические эндпоинты) — название аянамши, регистр не важен; по умолчанию LAHIRI. Для /api/astro/chart/ поле обязательно.
  Правильно: LAHIRI, KRISHNAMURTI, RAMAN, TRUE_CITRA.
  Неправильно: "kp-newcomb", "Lahiri ayanamsa". В /api/astro/chart/ неизвестное название вернёт 400.
• В маршрутах /api/astro/western/ и /api/astro/return/ поле ayanamsa по умолчанию равно TROPICAL; чтобы получить сидерические положения, передайте название аянамши.
• Эндпоинт без поля ayanamsa считает по Лахири. У /api/astro/prashna/jamakkol/ свой список в нижнем регистре: lahiri, true_citra, krishnamurti, raman.

• keys — JSON-массив точных названий из таблицы ключей эндпоинта.
  Правильно: ["tithi", "vaara", "rahu_kaalam"] в /api/astro/panchanga/.
  Неправильно: "tithi,vaara" (строка), "Tithi", "rahu_kaal".
• Некоторым ключам нужно дополнительное поле — оно указано в таблице ключей. Например, ключу phone_number в /api/astro/numerology/ нужно значение phone_number.
• Эндпоинт, у которого в справочнике нет таблицы ключей, например /api/astro/tithi/ или /api/astro/rahu-kaal/, всегда выполняет один и тот же расчёт; отправлять keys не нужно.

• chart_name в /api/astro/chart/ — PascalCase с учётом регистра. Передайте массив, чтобы получить несколько карт одним вызовом.
  Правильно: "RashiChart", ["RashiChart", "NavamsaChart", "DasamsaChart"].
  Неправильно: "rashi", "D9", "Navamsa".
• notation — в нижнем регистре: degree (десятичные градусы) или astrological (знак, градусы, минуты, секунды).
• Лунный узел — rahu в маршрутах карт (по умолчанию true, либо mean или both), node в маршрутах даш и Джаймини (по умолчанию true, либо mean), node_type в Human Design и прашне (по умолчанию mean, кроме /api/astro/prashna/, где поле обязательно).
• house_system в /api/astro/western/house-cusps/ — нижний регистр, слова через подчёркивание.
  Правильно: placidus (по умолчанию), whole_sign, equal, koch, porphyry, regiomontanus, campanus, topocentric.
  Неправильно: "whole-sign", "W".
• rashi в маршрутах рашифала — английские названия знаков.
  Правильно: aries, taurus, … pisces.
• system в /api/astro/numerology/ — chaldean (по умолчанию), pythagorean, chinese или vedic. У каждой системы свой набор ключей.
• spread в /api/astro/tarot/spread/ — three_card (по умолчанию), one_card, celtic_cross, horseshoe, relationship или situation.
• sequence в /api/astro/numerology/angel/ — увиденное число, строкой.
  Правильно: "1111", "444".
  Неправильно: 1111 (число).
• levels в шкалах даш — от 1 до 4, по умолчанию 3: 1 — только махадаши, 2 — плюс антардаши, 3 — плюс пратьянтардаши.

Каждый маршрут заканчивается слешем. Без него сервер отвечает 301 с редиректом на адрес со слешем, а большинство HTTP-клиентов повторяют запрос как GET без тела — и вызов не проходит. Копируйте написание маршрута точно: в одних — дефисы (/api/astro/rahu-kaal/), в других — подчёркивания (/api/astro/monthly_panchang/), а некоторые лежат вне /api/astro/ (/api/festivals/, /api/vrat-upavas/).

• /docs/agent-gotchas — Подводные камни
• /docs/agent-tasks — Шпаргалка для агентов