POST/api/astro/transit/1 кредит

Транзитні перетини

Цей ендпоінт шукає моменти, а не описує карту на фіксований час. Він відповідає на запитання на кшталт: коли Сонце наступного разу досягне 0 градусів Овна, коли Марс перетне певний градус між двома датами, коли Сатурн і Сонце наступного разу матимуть однакову екліптичну довготу і де саме перебуває тіло в певний момент. Два ключі — це перемикачі режиму, а не розрахунки. `set_default_transit` вмикає звичайні тропічні ефемериди, а `set_sidereal_transit` — сидеричні; обидва повертають null. Ключі запиту виконуються в тому порядку, у якому ви їх перелічили, тож якщо наступні пошуки мають бути сидеричними, поставте перемикач першим. Поля `planet`, `celestial`, `celestial1` і `celestial2` приймають назви ефемерид у верхньому регістрі (`SUN`, `MOON`, `MEAN_NODE`, `TRUE_NODE`, `CHIRON`, уранічні точки й кілька супутників планет) — це інший набір назв, ніж `Sun`/`Moon` на більшості інших ендпоінтів. `tz` — просте зміщення в годинах, яке застосовується до кожної повернутої мітки часу, `when` визначає, шукати 'after' чи 'before' опорного часу, а `datetime_start`/`datetime_end` обмежують вікно для `planet_transit`.

https://api.occultapi.com/api/astro/transit/

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

Результат «Транзитні перетини» в інтерфейсі — Дані цього ендпоінта в живому інтерфейсі. API повертає значення, а вигляд сторінки ви будуєте самі.

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

Передавайте ключ у заголовку 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' — різні моменти, і відповіді для них різні.
datetime_end	string (date-time)	обов’язковий
datetime_start	string (date-time)	обов’язковий
keys	array	обов’язковий	Які розрахунки повернути, у вигляді списку назв. Див. таблицю ключів цього ендпоінта; через нерозпізнану назву відхиляється весь запит. Один виклик коштує один кредит незалежно від кількості запитаних ключів, тож запитуйте все потрібне одразу, а не кількома викликами.
planet	string	обов’язковий	`SUNMOONMERCURYVENUSMARSJUPITERSATURNURANUSNEPTUNEPLUTOMEAN_NODETRUE_NODE` 36 допустимих значень: 10 планет, два місячні вузли, 6 астероїдів, 9 уранічних/фіктивних тіл і 9 супутників планет. Нерозпізнана назва не дає помилки, а мовчки перетворюється на None, і тоді збій стається глибше, всередині ядра ефемерид. Зверніть увагу: вузли записуються з підкресленням — MEAN_NODE / TRUE_NODE (альтернативних назв 'RAHU'/'KETU' немає).
tz	number (double)	обов’язковий	min -12 · max 14
celestial	string	необов’язковий	`SUNMOONMERCURYVENUSMARSJUPITERSATURNURANUSNEPTUNEPLUTOMEAN_NODETRUE_NODE` 36 допустимих значень: 10 планет, два місячні вузли, 6 астероїдів, 9 уранічних/фіктивних тіл і 9 супутників планет. Нерозпізнана назва не дає помилки, а мовчки перетворюється на None, і тоді збій стається глибше, всередині ядра ефемерид. Зверніть увагу: вузли записуються з підкресленням — MEAN_NODE / TRUE_NODE (альтернативних назв 'RAHU'/'KETU' немає).
celestial1	string	необов’язковий	`SUNMOONMERCURYVENUSMARSJUPITERSATURNURANUSNEPTUNEPLUTOMEAN_NODETRUE_NODE` 36 допустимих значень: 10 планет, два місячні вузли, 6 астероїдів, 9 уранічних/фіктивних тіл і 9 супутників планет. Нерозпізнана назва не дає помилки, а мовчки перетворюється на None, і тоді збій стається глибше, всередині ядра ефемерид. Зверніть увагу: вузли записуються з підкресленням — MEAN_NODE / TRUE_NODE (альтернативних назв 'RAHU'/'KETU' немає).
celestial2	string	необов’язковий	`SUNMOONMERCURYVENUSMARSJUPITERSATURNURANUSNEPTUNEPLUTOMEAN_NODETRUE_NODE` 36 допустимих значень: 10 планет, два місячні вузли, 6 астероїдів, 9 уранічних/фіктивних тіл і 9 супутників планет. Нерозпізнана назва не дає помилки, а мовчки перетворюється на None, і тоді збій стається глибше, всередині ядра ефемерид. Зверніть увагу: вузли записуються з підкресленням — MEAN_NODE / TRUE_NODE (альтернативних назв 'RAHU'/'KETU' немає).
degr	number (double)	необов’язковий
latitude	number (double)	необов’язковий	Широта місця в десяткових градусах. Додатні значення — північ, від’ємні — південь. Приклад: 26.9124 для Джайпура, 40.7128 для Нью-Йорка. Хвилини й секунди не приймаються — спершу переведіть їх у градуси. min -89.9 · max 89.9
longitude	number (double)	необов’язковий	Довгота місця в десяткових градусах. Додатні значення — схід, від’ємні — захід. Приклад: 75.7873 для Джайпура, -74.0060 для Нью-Йорка. Зверніть увагу на знак: без мінуса Нью-Йорк опиниться в Китаї. min -180 · max 180
nakshatras	string	необов’язковий	`special` НЕДІЄВИЙ ПАРАМЕТР на рівні HTTP: TransitView ніколи не передає його далі, тож він ні на що не впливає. У ядрі має сенс лише літерал 'special': він обирає таблицю nakshatras_special із 28 записів замість типової з 27.
when	string	необов’язковий	`afterbefore` Типове значення ядра — 'after'. Використовується ключами 'solar_crossing', 'find_moon_crossing', 'moon_node_crossing' і 'celestial_conjunction'.
x2cross	number (double)	необов’язковий

Доступні ключі (8)

Перелічіть у keys саме ті розрахунки, які вам потрібні. Один невідомий ключ — і відхиляється весь запит. Скільки б ключів ви не запитали, спишеться 1 кредит, тож збирайте їх в один виклик.

Ключ	Додаткові поля	Опис
celestial_conjunction	celestial1, celestial2, datetime_start, when	Перший момент після `datetime_start`, коли `celestial1` і `celestial2` мають однакову екліптичну довготу. Повертає об’єкт із `long1` і `long2` — двома довготами в знайдений момент, близькими, але не точно рівними, бо пошук сходиться до заданого допуску, — і `date`, міткою часу ISO.
find_moon_crossing	x2cross, date_time, tz, when	Момент, коли Місяць досягає екліптичної довготи, заданої в `x2cross`, з пошуком уперед чи назад від `date_time` відповідно до `when`. Повертає одну мітку часу ISO, зсунуту на `tz`. Оскільки Місяць проходить близько 13 градусів за добу, відповідь зазвичай у межах місяця від опорного часу.
moon_node_crossing	date_time, tz, when	Наступний або попередній перетин місячного вузла з пошуком від `date_time` у напрямку, заданому `when`. Повертає об’єкт із `date` — міткою часу ISO, зсунутою на `tz`, — а також `long` і `lat`, екліптичними довготою й широтою в цей момент. Корисно для визначення сезонів затемнень.
planet_transit	degr, planet, datetime_start, datetime_end, tz	Момент, коли тіло, назване в `planet`, перетинає екліптичну довготу, задану в `degr`, з пошуком між `datetime_start` і `datetime_end`. Повертає одну мітку часу ISO, зсунуту на `tz`, або null, якщо тіло не досягає цього градуса в межах вікна. На відміну від перетинів Сонця й Місяця, цей пошук обмежений, тож задайте діапазон, достатньо широкий, щоб охопити подію.
set_default_transit	—	Перемикач режиму, а не розрахунок: вмикає тропічні ефемериди (без аянамші) для решти запиту. Повертає null. Ключі виконуються в тому порядку, у якому ви їх перелічили, тож поставте його перед ключами перетинів, на які він має впливати.
set_sidereal_transit	—	Перемикач режиму, а не розрахунок: вмикає сидеричні ефемериди, тож наступні перетини й положення в тому самому запиті вимірюються відносно аянамші, а не тропічної нульової точки. Повертає null; його треба вказати перед ключами, на які він має впливати.
solar_crossing	x2cross, date_time, tz, when	Момент, коли Сонце досягає екліптичної довготи, заданої в `x2cross`, з пошуком уперед чи назад від `date_time` відповідно до `when`. Повертає одну мітку часу ISO, зсунуту на зміщення `tz` у годинах. Передайте 0, щоб знайти сидеричний новий рік, або натальну сонячну довготу, щоб знайти день народження з точністю до хвилини.
transit_details	celestial, date_time, tz	Повні дані про положення тіла, названого в `celestial`, на `date_time`. Повертає об’єкт із `longitude` — готовим рядком для відображення, `nakshatra` та її `nakshatra_lord`, `padam` (чверть накшатри, 1-4), `full_degree` (сидерична довгота, поділена на 30, тобто номер знака плюс пройдена частка знака), `latitude_shara` у форматі `{degrees, minutes, seconds}`, `speed` у градусах за добу як рядок, `right_ascension` у форматі 'hh.mm.ss.ss' і `declination_kranti` у градусах як рядок.

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

curl -X POST https://api.occultapi.com/api/astro/transit/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date_time":"2024-11-20T06:52:42.466Z","keys":["set_sidereal_transit","planet_transit","solar_crossing","celestial_conjunction","transit_details"],"latitude":26.1046,"longitude":75.7873,"tz":5.5,"planet":"MARS","datetime_start":"2024-11-20T06:52:42.466Z","datetime_end":"2040-11-20T06:52:42.466Z","degr":0,"x2cross":0,"celestial1":"SATURN","celestial2":"SUN","celestial":"MARS","when":"after"}'

Відповідь

{
  "data": {
    "set_sidereal_transit": null,
    "planet_transit": "2026-05-11T12:38:41+05:30",
    "solar_crossing": "2025-04-14T03:21:25+05:30",
    "celestial_conjunction": {
      "long1": 327.886,
      "long2": 327.877,
      "date": "2025-03-12T10:13:52.466000Z"
    },
    "transit_details": {
      "longitude": "4° Mesh 4'° 25\"",
      "nakshatra": "Makha",
      "padam": 2,
      "nakshatra_lord": "Ketu",
      "full_degree": 4.15,
      "latitude_shara": {
        "degrees": 2,
        "minutes": 5,
        "seconds": 52.8
      },
      "speed": "0.2",
      "right_ascension": "08.29.10.92",
      "declination_kranti": "21.19"
    }
  },
  "status": 200,
  "is_error": false,
  "message": "successful"
}

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

Помилки

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