/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`) заданной даты в этом месте. Возвращает список из двух элементов: момент восхода как datetime в местном времени, заданном `time_zone`, затем исходные значения юлианского дня. Какое определение «восхода» применяется, зависит от переключателя восхода или диска, стоящего перед этим ключом в массиве keys. Если тело не восходит или не заходит в пределах окна поиска — Луна на высоких широтах или Солнце во время полярного дня, — внутренний поиск завершается неудачей и возвращается "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`: [местный datetime, исходные значения юлианского дня]. Несмотря на префикс `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. Подробнее — в справочнике ошибок.