/api/astro/celestial/1 кредитПоложення небесних тіл
Сирі ефемериди для одного чи кількох тіл: де планета, як швидко вона рухається, коли сходить і заходить, чи ретроградна вона. Це астрономічна основа решти API, доступна напряму, і вона далеко не обмежується дев’ятьма ведичними грахами: можна запитати зовнішні планети, Хірон і астероїди, фіктивні точки уранічної школи та кілька супутників планет. Ключі бувають двох видів. Ключі `set_*` — перемикачі: вони змінюють спосіб обчислення положень або часу сходу й заходу (геоцентричний, топоцентричний чи геліоцентричний; видимий чи істинний; з нутацією чи без; сидеричний чи тропічний; індійський схід чи схід за центром диска) і кожен повертає null. Ключі `get_*`, а також `rise_time`, `set_time`, `is_retrograde` і `is_stationary` повертають значення. Ключі виконуються в тому порядку, у якому ви їх перелічили, тож перемикач впливає лише на ключі зі значеннями, що стоять після нього в масиві. `planet_names` приймає список назв у верхньому регістрі, і ці назви стають ключами відповіді: виклик для MARS повертає `{"data": {"MARS": {"get_longitude": 123.45}}}`. Через нерозпізнану назву запит не відхиляється: для неї просто повертається `{"error": "Unknown planet '<name>'"}`. Зверніть увагу: вузли тут називаються MEAN_NODE і TRUE_NODE, а не 'northtruenode', як у /api/astro/chart/.
https://api.occultapi.com/api/astro/celestial/Автентифікація
Передавайте ключ у заголовку X-API-Key. Ключ — це серверні облікові дані: ніколи не вставляйте його в JavaScript, що виконується в браузері, чи в мобільний застосунок.
X-API-Key: yt_live_a1b2c3d4_…
Content-Type: application/jsonПоля запиту
| Поле | Тип | Обов’язкове | Примітки |
|---|---|---|---|
| altitude | number (double) | обов’язковий | |
| 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' — різні моменти, і відповіді для них різні. Обмеження ФОРМАТУ, а не перелік значень. DRF DateTimeField: лише ISO-8601 (типові формати введення DRF), напр. "2026-09-01T06:00:00+05:30", "2026-09-01T06:00:00Z" або "2026-09-01 06:00:00" (без часового поясу вважається UTC). |
| keys | array | обов’язковий | Які розрахунки повернути, у вигляді списку назв. Див. таблицю ключів цього ендпоінта; через нерозпізнану назву відхиляється весь запит. Один виклик коштує один кредит незалежно від кількості запитаних ключів, тож запитуйте все потрібне одразу, а не кількома викликами. set_default_risingset_hindu_risingset_disc_center_refractionset_disc_bottom_refractionset_disc_center_no_refractionset_disc_bottom_no_refractionset_default_positionsset_true_positionsset_topocentric_positionsset_heliocentric_positionsset_barycentric_positionsset_astrometric_positionsМасив рядків. Ключі `set_*` змінюють прапорці розрахунку в об’єкті Celestial; ключі `get_*` / `rise_time` / `set_time` / `is_*` повертають значення. |
| planet_names | array | обов’язковий | SUNMOONMERCURYVENUSMARSJUPITERSATURNURANUSNEPTUNEPLUTOMEAN_NODETRUE_NODEМасив рядків, мінімальна довжина 1. Зверніть увагу: вузли тут називаються 'MEAN_NODE'/'TRUE_NODE', а не в стилі 'northtruenode', як у відповіді карти. Через нерозпізнану назву запит не відхиляється: для неї просто повертається {"error": "Unknown planet '<X>'"}. |
| time_zone | number (double) | обов’язковий | min -12 · max 14 |
| latitude | number (double) | необов’язковий | Широта місця в десяткових градусах. Додатні значення — північ, від’ємні — південь. Приклад: 26.9124 для Джайпура, 40.7128 для Нью-Йорка. Хвилини й секунди не приймаються — спершу переведіть їх у градуси. min -89.9 · max 89.9 |
| longitude | number (double) | необов’язковий | Довгота місця в десяткових градусах. Додатні значення — схід, від’ємні — захід. Приклад: 75.7873 для Джайпура, -74.0060 для Нью-Йорка. Зверніть увагу на знак: без мінуса Нью-Йорк опиниться в Китаї. min -180 · max 180 |
Доступні ключі (31)
Перелічіть у keys саме ті розрахунки, які вам потрібні. Один невідомий ключ — і відхиляється весь запит. Скільки б ключів ви не запитали, спишеться 1 кредит, тож збирайте їх в один виклик.
| Ключ | Додаткові поля | Опис |
|---|---|---|
| get_altitude | date_time, latitude, longitude, altitude | Висота тіла над горизонтом у градусах, із шістьма знаками після крапки; від’ємне значення означає, що тіло під горизонтом. Потребує `latitude`, `longitude` і `altitude` у метрах. |
| get_apsis | date_time | Найближчі афелій і перигелій — точки, де тіло найдалі від Сонця і найближче до нього. Повертає об’єкт `{Aphelion, Perihelion}` з датою й часом UTC для кожної точки; їх шукають уперед від заданого моменту. Доступно лише для тіл, які охоплює модель. |
| get_azimuth | date_time, latitude, longitude, altitude | У якому місці горизонту шукати тіло: градуси від півночі за годинниковою стрілкою, одне число із шістьма знаками після крапки. Потребує `latitude`, `longitude` і `altitude`; рефракцію враховує, якщо перед цим не встановлено перемикач без рефракції. |
| get_declination | date_time | Схилення — кутова відстань тіла на північ чи на південь від небесного екватора — у вигляді об’єкта з `degrees`, `minutes` і `seconds`. |
| get_distance | date_time | Відстань від спостерігача в астрономічних одиницях, округлена до трьох знаків після крапки. Одне число; для Місяця це невелика частка AU. |
| get_ecliptic_speeds | date_time | Швидкість руху тіла: об’єкт із `longitude_speed` і `latitude_speed` у градусах за добу та `distance_speed` в AU за добу, кожне значення із шістьма знаками після крапки. Від’ємна швидкість за довготою означає ретроградний рух. |
| get_equatorial_speeds | date_time | Рух в екваторіальних координатах: об’єкт із `right_ascension_speed` і `declination_speed` у градусах за добу та `distance_speed` в AU за добу, кожне із шістьма знаками після крапки. |
| get_illumination | date_time | Видима зоряна величина тіла в цей момент — одне число із шістьма знаками після крапки; що менше (від’ємніше) значення, то яскравіше тіло. Доступно лише для тіл, які охоплює модель освітленості; для інших повертається помилка. |
| get_latitude | date_time | Екліптична широта в градусах із трьома знаками після крапки: наскільки тіло вище чи нижче площини екліптики. Одне число; південна широта від’ємна. |
| get_longitude | date_time | Екліптична довгота в градусах, від 0 до 360, округлена до трьох знаків після крапки, — одне число. Тропічна вона чи сидерична, залежить від увімкненого режиму положень. |
| get_right_ascension | date_time | Пряме сходження — екваторіальний відповідник довготи — у вигляді об’єкта з `hours`, `minutes` і `seconds`, а не в десяткових градусах. |
| is_retrograde | date_time | True, коли швидкість тіла за довготою від’ємна, тобто коли воно візуально рухається зодіаком назад. Одне булеве значення. |
| is_stationary | date_time | Груба перевірка стаціонарності: true, коли дробова частина добової швидкості тіла за довготою після округлення до трьох знаків дорівнює нулю. Повертає булеве значення; через такий спосіб перевірки це лише орієнтир, а не точний момент станції. |
| rise_time | date_time, geopos | Схід тіла; пошук іде від місцевої опівночі (за зміщенням `time_zone`) заданої дати в цьому місці. Повертає список із двох елементів: момент сходу як дату й час у місцевому часі за `time_zone`, а потім сирі значення юліанського дня. Яке визначення «сходу» діє, залежить від перемикача сходу чи диска, що стоїть перед цим ключем у масиві. Якщо тіло не сходить або не заходить у межах вікна пошуку (Місяць на високих широтах чи Сонце під час полярного дня), базовий пошук не вдається і повертається "2000-11-24T12:00:00Z" — нульовий юліанський день, а не реальний момент. Вважайте саме це значення відсутністю результату. /api/astro/sunrise/ і /api/astro/moonrise/ у такому разі повертають null. |
| set_astrometric_j_positions | — | Перемикає на астрометричні положення відносно середнього рівнодення J2000; нутацію, аберацію та відхилення світла вимкнено. Повертає null. |
| set_astrometric_positions | — | Перемикає на астрометричні положення: час поширення світла враховується, а річна аберація й гравітаційне відхилення світла — ні. Повертає null. |
| set_barycentric_positions | — | Перемикає на барицентричні положення відносно барицентра Сонячної системи. Повертає null і працює лише для фізичних тіл, а не для вузлів чи апогеїв. |
| set_default_positions | — | Перемикач, а не значення: вмикає видимі геоцентричні положення зі швидкостями — це режим за замовчуванням (TROPICAL) для цього ендпоінта. Повертає null. Перемикачі `set_*` діють лише на ключі, перелічені після них у `keys`, тож порядок важливий: поставте цей ключ першим або після іншого перемикача, щоб повернути типовий режим. Зверніть увагу: однойменний ключ на /api/astro/star/ натомість вмикає СИДЕРИЧНІ положення. |
| set_default_rising | — | Відновлює типове визначення сходу й заходу для `rise_time` і `set_time`. Перемикач, а не значення: повертає null і впливає лише на ключі, перелічені після нього. |
| set_disc_bottom_no_refraction | — | Визначає схід і захід за нижнім краєм диска з вимкненою рефракцією. Повертає null. |
| set_disc_bottom_refraction | — | Визначає схід і захід за нижнім краєм диска із застосуванням атмосферної рефракції. Повертає null. |
| set_disc_center_no_refraction | — | Визначає схід і захід за центром диска з вимкненою рефракцією — геометрично, а не так, як це видно спостерігачеві. Повертає null, а всі подальші `get_azimuth` і `get_altitude` обчислюються без урахування атмосфери. |
| set_disc_center_refraction | — | Визначає схід і захід за центром диска з урахуванням атмосферної рефракції. Повертає null, а всі подальші `get_azimuth` і `get_altitude` також обчислюються з рефракцією. |
| set_heliocentric_positions | — | Перемикає на геліоцентричні положення відносно центру Сонця. Повертає null. Сонце, місячні вузли та місячні апогеї в цьому режимі повертаються як нуль. |
| set_hindu_rising | — | Перемикає час сходу й заходу на індійське визначення. Повертає null; діє на ключі `rise_time` і `set_time`, що стоять після нього в масиві. |
| set_jpl_horizons_positions | — | Перемикає на видимі положення, обчислені так само, як у JPL Horizons, щоб результати можна було звірити з цим сервісом. Повертає null. |
| set_mean_equinox_positions | — | Перемикає на положення відносно середнього рівнодення дати, вимикаючи нутацію. Повертає null. |
| set_sidereal_positions | — | Перемикає на сидеричні положення, тобто тропічна довгота мінус аянамша. Повертає null. Сама аянамша задається не тут, тож діє поточний сидеричний режим. |
| set_time | date_time, geopos | Захід тіла; пошук іде від місцевої опівночі (за зміщенням `time_zone`) заданої дати в цьому місці. Структура та сама, що й у `rise_time`: [місцеві дата й час, сирі значення юліанського дня]. Попри префікс `set_` цей ключ повертає значення, а не є перемикачем. Якщо тіло не сходить або не заходить у межах вікна пошуку (Місяць на високих широтах чи Сонце під час полярного дня), базовий пошук не вдається і повертається "2000-11-24T12:00:00Z" — нульовий юліанський день, а не реальний момент. Вважайте саме це значення відсутністю результату. /api/astro/sunrise/ і /api/astro/moonrise/ у такому разі повертають null. |
| set_topocentric_positions | latitude, longitude, altitude | Перемикає на топоцентричні положення відносно місця самого спостерігача, а не центру Землі. Потребує `latitude`, `longitude` і `altitude` у метрах; повертає null. Різниця помітна лише для Місяця. |
| set_true_positions | — | Перемикає на істинні геометричні положення без урахування часу поширення світла — там, де тіло є насправді, а не там, де його видно. Повертає null. |
Приклад запиту
curl -X POST https://api.occultapi.com/api/astro/celestial/ \
-H "X-API-Key: $OCCULT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"date_time":"2024-11-20T08:40:08.658Z","keys":["set_default_positions","set_hindu_rising"],"latitude":26.9124,"longitude":75.7873,"time_zone":5.5,"altitude":0,"planet_names":["SUN"]}'Відповідь
{
"data": {
"SUN": {
"set_default_positions": null,
"set_hindu_rising": null
}
},
"status": 200,
"is_error": false,
"message": "successful"
}Записано з реального виклику з точно таким запитом, як вище. Результати лежать у data під тими ключами, які ви запитали.
Помилки
Помилки обліку кредитів мають вигляд { "error": "…", "message": "<code>", "is_error": true }. Людям показуйте error, а логіку будуйте на message. Детальніше — у довіднику помилок.