POST/api/astro/return/solar/1 кредит

Сонячне повернення

Точний момент, коли Сонце повертається на ту екліптичну довготу, яку мало при народженні, — астрологічний день народження і карта, за якою розглядають наступний рік. Зазвичай це НЕ календарний день народження. Відносно календаря повернення зсувається приблизно на шість годин щороку (це та сама чверть доби, через яку існують високосні роки), тож воно може випасти на день раніше чи пізніше. Кілька років поспіль можна запитати через `count`, а почати не від народження — через `search_from`. Кожен результат містить `error_arcseconds` — відстань між фактичним положенням Сонця і натальним градусом, тож точність відповіді можна перевірити, а не вірити на слово.

https://api.occultapi.com/api/astro/return/solar/

Спробувати запит

Автентифікація

Передавайте ключ у заголовку X-API-Key. Ключ — це серверні облікові дані: ніколи не вставляйте його в JavaScript, що виконується в браузері, чи в мобільний застосунок.

X-API-Key: yt_live_a1b2c3d4_…
Content-Type: application/json

Поля запиту

Поле	Тип	Обов’язкове	Примітки
date_time	string (date-time)	обов’язковий	Момент, для якого виконується розрахунок, у форматі ISO 8601. ЗАВЖДИ вказуйте зміщення або Z у кінці: значення без часового поясу читається як Asia/Kolkata (UTC+05:30), а не UTC, і може повернути результат за попередній день із кодом 200. '2026-09-01T06:00:00Z' і '2026-09-01 06:00:00' — різні моменти, і відповіді для них різні.
ayanamsa	string	необов’язковий	TROPICAL (за замовчуванням) або назва аянамші, напр. LAHIRI, KRISHNAMURTI, RAMAN чи FAGAN_BRADLEY, без урахування регістру. Сидерична аянамша віднімає своє значення на кожен момент від кожної повернутої довготи.
count	integer	необов’язковий	Кількість послідовних повернень у відповіді, не більше 24. min 1 · max 24
exact_passes	boolean	необов’язковий	Увімкнути пошук з урахуванням станцій: він знаходить кожне проходження, зокрема два з різницею в кілька годин по обидва боки від станції, і групує проходження за геоцентричною ретроградною петлею (зокрема для Меркурія й Венери). Додає до відповіді "exact_passes": true. За замовчуванням false — пошук працює, як і раніше.
include_asteroid_lilith	boolean	необов’язковий	Додати астероїд (1181) Ліліт (це не Чорний Місяць Ліліт) під назвою "asteroid_lilith" після інших тіл.
include_lilith	boolean	необов’язковий	Додати Чорний Місяць Ліліт (середній місячний апогей) як тіло з назвою "lilith", після інших тіл.
keys	array	необов’язковий	Які розрахунки повернути, у вигляді списку назв. Див. таблицю ключів цього ендпоінта; через нерозпізнану назву відхиляється весь запит. Один виклик коштує один кредит незалежно від кількості запитаних ключів, тож запитуйте все потрібне одразу, а не кількома викликами.
latitude	number (double)	необов’язковий	Широта місця в десяткових градусах. Додатні значення — північ, від’ємні — південь. Приклад: 26.9124 для Джайпура, 40.7128 для Нью-Йорка. Хвилини й секунди не приймаються — спершу переведіть їх у градуси.
longitude	number (double)	необов’язковий	Довгота місця в десяткових градусах. Додатні значення — схід, від’ємні — захід. Приклад: 75.7873 для Джайпура, -74.0060 для Нью-Йорка. Зверніть увагу на знак: без мінуса Нью-Йорк опиниться в Китаї.
search_from	string (date-time)	необов’язковий	Момент, з якого почати пошук замість моменту народження.
timezone_as_float	number (double)	необов’язковий	Зміщення місця від UTC у годинах, десятковим дробом. Приклад: 5.5 для Індії (UTC+05:30), -5 для Нью-Йорка взимку, 5.75 для Непалу. Його НЕ звіряють із date_time: якщо значення розходяться, ви отримаєте успішну відповідь для неправильного моменту, тож беріть обидва з одного джерела. Використовуйте зміщення, чинне на ту дату, а не сьогоднішнє: для народження влітку в країні з переходом на літній час потрібне літнє зміщення. min -12 · max 14

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

curl -X POST https://api.occultapi.com/api/astro/return/solar/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date_time":"1990-05-10T19:55:00+05:30","timezone_as_float":5.5,"search_from":"2026-01-01T00:00:00+00:00","count":3}'

Відповідь

{
  "data": {
    "body": "sun",
    "natal_longitude": 49.66766,
    "sign": "Taurus",
    "sign_index": 2,
    "degree_in_sign": 19.6677,
    "natal_datetime_utc": "1990-05-10T14:25:00Z",
    "count": 3,
    "returns": [
      {
        "exact": "2026-05-10T07:34:40Z",
        "pass_count": 1,
        "passes": [
          {
            "body": "sun",
            "datetime_utc": "2026-05-10T07:34:40Z",
            "julian_day_ut": 2461170.81573688,
            "longitude": 49.66766,
            "error_arcseconds": 0,
            "retrograde": false,
            "sign": "Taurus",
            "sign_index": 2,
            "degree_in_sign": 19.6677
          }
        ]
      },
      {
        "exact": "2027-05-10T13:07:54Z",
        "pass_count": 1,
        "passes": [
          {
            "body": "sun",
            "datetime_utc": "2027-05-10T13:07:54Z",
            "julian_day_ut": 2461536.04715718,
            "longitude": 49.66766,
            "error_arcseconds": 0,
            "retrograde": false,
            "sign": "Taurus",
            "sign_index": 2,
            "degree_in_sign": 19.6677
          }
        ]
      },
      {
        "exact": "2028-05-09T19:00:18Z",
        "pass_count": 1,
        "passes": [
          {
            "body": "sun",
            "datetime_utc": "2028-05-09T19:00:18Z",
            "julian_day_ut": 2461901.29187794,
            "longitude": 49.66766,
            "error_arcseconds": 0,
            "retrograde": false,
            "sign": "Taurus",
            "sign_index": 2,
            "degree_in_sign": 19.6677
          }
        ]
      }
    ]
  },
  "status": 200,
  "is_error": false,
  "message": "successful"
}

Записано з реального виклику з точно таким запитом, як вище. Результати лежать у data.

Помилки

Помилки обліку кредитів мають вигляд { "error": "…", "message": "<code>", "is_error": true }. Людям показуйте error, а логіку будуйте на message. Детальніше — у довіднику помилок.