Эфемериды
Эфемериды
/api/v1/ephemeris/calculateЗапрос положений планет по одной временной метке или полному диапазону дат с настраиваемыми шагами. Метаданные астрологического уровня, дополнительные аспекты и вывод таблиц, предназначенные для календарей, экспорта, и ежемесячные представления эфемерид.
Полный URL
https://api.freeastroapi.com/api/v1/ephemeris/calculateУдобство GET /api/v1/ephemeris псевдоним также доступен для рабочих процессов со строкой запроса.
Пример ежемесячной сетки
Это самый ясный способ понять, что table_style=сетка возвращает: одна строка в день, один столбец на тело, с отформатированными позициями, готовыми для календаря внешнего интерфейса или представления экспорта.
| Date | Weekday | Sid.t | Sun | Moon | Mercury | Venus | Mars | Jupiter | Saturn |
|---|---|---|---|---|---|---|---|---|---|
| 1 | Sun | 10:35:16 | 10°24' Pis | 09°07' Leo | 21°58' Pis Rx | 23°13' Pis | 28°45' Aqu | 15°15' Can Rx | 01°43' Ari |
| 2 | Mon | 10:39:12 | 11°25' Pis | 22°53' Leo | 21°28' Pis Rx | 24°28' Pis | 29°32' Aqu | 15°13' Can Rx | 01°51' Ari |
| 3 | Tue | 10:43:09 | 12°25' Pis | 06°25' Vir | 20°50' Pis Rx | 25°42' Pis | 00°19' Pis | 15°12' Can Rx | 01°58' Ari |
| 4 | Wed | 10:47:05 | 13°25' Pis | 19°43' Vir | 20°05' Pis Rx | 26°57' Pis | 01°06' Pis | 15°10' Can Rx | 02°05' Ari |
| 5 | Thu | 10:51:02 | 14°25' Pis | 02°44' Lib | 19°15' Pis Rx | 28°12' Pis | 01°54' Pis | 15°09' Can Rx | 02°12' Ari |
| 6 | Fri | 10:54:59 | 15°25' Pis | 15°28' Lib | 18°19' Pis Rx | 29°27' Pis | 02°41' Pis | 15°08' Can Rx | 02°20' Ari |
| 7 | Sat | 10:58:55 | 16°25' Pis | 27°56' Lib | 17°20' Pis Rx | 00°41' Ari | 03°28' Pis | 15°07' Can Rx | 02°27' Ari |
| 8 | Sun | 11:02:52 | 17°25' Pis | 10°10' Sco | 16°20' Pis Rx | 01°56' Ari | 04°16' Pis | 15°06' Can Rx | 02°34' Ari |
| 9 | Mon | 11:06:48 | 18°25' Pis | 22°14' Sco | 15°19' Pis Rx | 03°10' Ari | 05°03' Pis | 15°06' Can Rx | 02°41' Ari |
| 10 | Tue | 11:10:45 | 19°25' Pis | 04°10' Sag | 14°19' Pis Rx | 04°25' Ari | 05°50' Pis | 15°05' Can Rx | 02°49' Ari |
| 11 | Wed | 11:14:41 | 20°25' Pis | 16°03' Sag | 13°22' Pis Rx | 05°40' Ari | 06°37' Pis | 15°05' Can Rx | 02°56' Ari |
| 12 | Thu | 11:18:38 | 21°25' Pis | 27°57' Sag | 12°28' Pis Rx | 06°54' Ari | 07°25' Pis | 15°05' Can | 03°04' Ari |
| 13 | Fri | 11:22:34 | 22°25' Pis | 09°57' Cap | 11°38' Pis Rx | 08°09' Ari | 08°12' Pis | 15°06' Can | 03°11' Ari |
| 14 | Sat | 11:26:31 | 23°25' Pis | 22°09' Cap | 10°53' Pis Rx | 09°23' Ari | 08°59' Pis | 15°06' Can | 03°18' Ari |
| 15 | Sun | 11:30:28 | 24°25' Pis | 04°35' Aqu | 10°14' Pis Rx | 10°38' Ari | 09°46' Pis | 15°07' Can | 03°26' Ari |
| 16 | Mon | 11:34:24 | 25°24' Pis | 17°19' Aqu | 09°41' Pis Rx | 11°52' Ari | 10°34' Pis | 15°08' Can | 03°33' Ari |
| 17 | Tue | 11:38:21 | 26°24' Pis | 00°24' Pis | 09°14' Pis Rx | 13°06' Ari | 11°21' Pis | 15°09' Can | 03°41' Ari |
| 18 | Wed | 11:42:17 | 27°24' Pis | 13°51' Pis | 08°54' Pis Rx | 14°21' Ari | 12°08' Pis | 15°10' Can | 03°48' Ari |
| 19 | Thu | 11:46:14 | 28°24' Pis | 27°39' Pis | 08°39' Pis Rx | 15°35' Ari | 12°55' Pis | 15°11' Can | 03°56' Ari |
| 20 | Fri | 11:50:10 | 29°23' Pis | 11°44' Ari | 08°31' Pis Rx | 16°49' Ari | 13°42' Pis | 15°13' Can | 04°03' Ari |
| 21 | Sat | 11:54:07 | 00°23' Ari | 26°03' Ari | 08°30' Pis | 18°04' Ari | 14°30' Pis | 15°15' Can | 04°10' Ari |
| 22 | Sun | 11:58:03 | 01°23' Ari | 10°30' Tau | 08°34' Pis | 19°18' Ari | 15°17' Pis | 15°17' Can | 04°18' Ari |
| 23 | Mon | 12:02:00 | 02°22' Ari | 24°59' Tau | 08°43' Pis | 20°32' Ari | 16°04' Pis | 15°19' Can | 04°25' Ari |
| 24 | Tue | 12:05:57 | 03°22' Ari | 09°26' Gem | 08°58' Pis | 21°46' Ari | 16°51' Pis | 15°21' Can | 04°33' Ari |
| 25 | Wed | 12:09:53 | 04°21' Ari | 23°45' Gem | 09°18' Pis | 23°00' Ari | 17°38' Pis | 15°24' Can | 04°40' Ari |
| 26 | Thu | 12:13:50 | 05°21' Ari | 07°55' Can | 09°43' Pis | 24°15' Ari | 18°25' Pis | 15°27' Can | 04°48' Ari |
| 27 | Fri | 12:17:46 | 06°20' Ari | 21°52' Can | 10°13' Pis | 25°29' Ari | 19°12' Pis | 15°30' Can | 04°55' Ari |
| 28 | Sat | 12:21:43 | 07°19' Ari | 05°36' Leo | 10°47' Pis | 26°43' Ari | 19°59' Pis | 15°33' Can | 05°03' Ari |
| 29 | Sun | 12:25:39 | 08°19' Ari | 19°08' Leo | 11°25' Pis | 27°57' Ari | 20°46' Pis | 15°36' Can | 05°10' Ari |
| 30 | Mon | 12:29:36 | 09°18' Ari | 02°27' Vir | 12°07' Pis | 29°11' Ari | 21°33' Pis | 15°39' Can | 05°18' Ari |
| 31 | Tue | 12:33:32 | 10°17' Ari | 15°34' Vir | 12°53' Pis | 00°25' Tau | 22°20' Pis | 15°43' Can | 05°25' Ari |
Выберите JSON
Используйте формат = JSON когда вам нужен один снимок или удобный для машины ответ диапазона для логики приложения.
Выберите строки/столбцы
Используйте table_style=строки или columns когда вам нужен более крупный экспорт, обработка в стиле CSV или пользовательские преобразования UI.
Выберите сетку
Используйте table_style=сетка если вам нужна таблица эфемерид в виде месяца со встроенным дневным и звездным временем.
Наиболее распространенные запросы
curl -X POST "https://api.freeastroapi.com/api/v1/ephemeris/calculate" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"start": "2026-03-01T00:00:00Z",
"bodies": ["Sun", "Moon", "Mercury"],
"include_moon_void_of_course": true,
"fixed_stars": ["Spica", "Regulus"]
}'curl -G "https://api.freeastroapi.com/api/v1/ephemeris" \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "start=2026-03-01T00:00:00Z" \
--data-urlencode "end=2026-03-31T00:00:00Z" \
--data-urlencode "step=1d" \
--data-urlencode "response_mode=table" \
--data-urlencode "table_style=grid" \
--data-urlencode "bodies=Sun,Moon,Mercury,Venus,Mars,Jupiter,Saturn,Uranus,Neptune,Pluto,Chiron,True_Lilith"curl -G "https://api.freeastroapi.com/api/v1/ephemeris" \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "start=2026-03-14T04:00:00Z" \
--data-urlencode "end=2026-03-14T08:00:00Z" \
--data-urlencode "step=5m" \
--data-urlencode "bodies=Moon,Sun"Ключевые параметры
| Parameter | Type | Req | Description |
|---|---|---|---|
| start | string | Да | Требуемая дата и время ISO. Если указан только start, эндпоинт возвращает один снимок на этот момент. |
| end | string | Нет | Необязательная дата и время ISO для запросов диапазона. Для начала должно быть больше или равно. |
| step | string | Нет | Целый минутный/часовой/дневной интервал, например 1 м, 5 м, 15 м, 1 ч, 6 ч, 1 д или 7 дн. По умолчанию: 1д. |
| city | string | Нет | Только POST. Работает как natal: если указано без широты и долготы, серверная часть автоматически определяет координаты. |
| lat | float | Нет | Широта. Если указаны широта и долгота, они переопределяют поиск города и используются напрямую. |
| lng | float | Нет | Долгота. Требуется вместе с lat для прямых запросов координат. |
| tz_str | string | Нет | Строка часового пояса или AUTO. AUTO использует разрешенные координаты и дату для определения часового пояса. |
| bodies | array[str] | csv | Нет | Запрошенные тела или точки. Принимает массив POST или строку GET, разделенную запятыми. |
| format | string | Нет | json или таблицу. По умолчанию: json. |
| response_mode | string | Нет | Псевдоним формата. Полезно для запросов к таблицам в рабочих процессах обработки строк запросов. |
| table_style | string | Нет | строки, столбцы или сетка. Сетка — это выходные данные календаря в стиле месяца. |
| zodiac_type | string | Нет | tropical (по умолчанию) или sidereal. |
| sidereal_ayanamsa | string | Нет | Используется только тогда, когда zodiac_type=звездный. Соответствует натальным соглашениям об именах. |
| house_system | string | Нет | Система домов, используемая при расчете домов или углов. По умолчанию: Плацидус. |
| include_aspects | boolean | Нет | Если true, включает данные аспекта для каждого снимка. |
| include_minor_aspects | boolean | Нет | Если true, аспекты расширяются, включая второстепенные типы аспектов. |
| include_moon_void_of_course | boolean | Нет | Если true, добавляется астрология.moon_void_of_course с текущим состоянием VOC, следующим входом знака Moon и следующим применением основного аспекта Moon перед входом, если он существует. |
| include_fixed_stars | boolean | Нет | Если true, возвращает набор астрологических фиксированных звезд по умолчанию в fixed_stars для каждого снимка. |
| fixed_stars | array[str] | csv | Нет | Необязательный явный список фиксированных звезд. Принимает массив POST или строку GET, разделенную запятыми, например Spica,Regulus. |
| include_houses | boolean | Нет | Если true, возвращает дома. Включается автоматически, когда координаты доступны, если явно не установлено значение false. |
| include_angles | boolean | Нет | Если true, возвращает данные восходящего/MC/связанного угла. Включается автоматически, когда координаты доступны, если явно не установлено значение false. |
Поведение местоположения
- Рекомендуемый поток: используйте Поиск города, дайте пользователю выбрать точный результат, а затем отправьте
lat,lng, и в идеалеtz_str. cityonPOST /api/v1/ephemeris/calculateэто запасной вариант для удобства. Если вы отправляете только город, серверная часть автоматически определяет координаты.- Если у вас уже есть координаты, пришлите их. Не отправляйте обратно только название города после поиска города, если только вы не хотите, чтобы серверная часть выполнила второй поиск.
- При наличии координат дома и углы включаются автоматически, если вы явно не отключите их.
Пределы диапазона
table_style=сеткапредназначен для отображения в виде месяца и ограничен31ряды. Большие запросы возвращаются400 grid_range_too_large.- Используйте
1hи1dдля стандартных таблиц и экспорта. - Используйте мельчайшие шаги, такие как
1mили5mтолько для работы по точному времени. - Диапазоны минутного уровня ограничены
1440ряды, примерно24hat1m. Большие запросы возвращаются400 minute_range_too_large. rowsиcolumnsразрешить экспорт большего размера, при этом все равно будет соблюдаться общее ограничение строки эндпоинта.
Moon void of course
- Установите
include_moon_void_of_course=trueдобавитьmoon_void_of_courseобъект подastrologyдля каждого снимка. - В расчетах используются точные основные аспекты Moon к Солнцу, Меркурию, Венере, Марсу, Юпитеру и Сатурну до того, как Moon меняет знак.
- Для ответов таблицы один и тот же объект доступен внутри каждого
raw_rows[].астрологияpayload.
Поддерживаемые тела
Основные тела
Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto
Узлы и лунные точки
Mean Node, True Node, Lilith, True Lilith
Астероиды и малые тела
Chiron, Pholus, Ceres, Pallas, Juno, Vesta
Координатные точки
Ascendant, MC, Vertex, Part of Fortune
Точки, основанные на координатах, требуют lat и lng.
Примеры ответов
{
"meta": {
"start": "2026-03-01T00:00:00Z",
"end": null,
"step": null,
"rows": 1,
"bodies": ["Sun", "Moon", "Mercury"],
"format": "json",
"zodiac_type": "tropical",
"sidereal_ayanamsa": null,
"timezone": "UTC"
},
"data": {
"timestamp": "2026-03-01T00:00:00Z",
"local_timestamp": "2026-03-01T00:00:00+00:00",
"subject": {
"datetime": "2026-03-01T00:00:00+00:00",
"location": {
"city": null,
"lat": null,
"lng": null,
"timezone": "UTC"
},
"settings": {
"julian_day": 2461100.5,
"julian_day_tt": 2461100.5007972275,
"delta_t_days": 0.0007972275448330983,
"delta_t_seconds": 68.8804598735797,
"zodiac_type": "Tropical",
"house_system": "placidus"
}
},
"bodies": {
"Sun": {
"id": "sun",
"name": "Sun",
"sign": "Pisces",
"sign_abbr": "Pis",
"sign_id": "pisces",
"pos": 10.406,
"abs_pos": 340.406,
"retrograde": false,
"speed": 1.0037,
"is_stationary": false,
"latitude_deg": 0.000076,
"distance_au": 0.990714622,
"position_text": "10°24' Pisces",
"degree_in_sign": 10.406,
"longitude_deg": 340.406,
"motion_state": "direct"
},
"Moon": {
"id": "moon",
"name": "Moon",
"sign": "Leo",
"sign_abbr": "Leo",
"sign_id": "leo",
"pos": 9.117,
"abs_pos": 129.117,
"retrograde": false,
"speed": 13.8619,
"is_stationary": false,
"latitude_deg": 2.635536,
"distance_au": 0.002504401,
"position_text": "09°07' Leo",
"degree_in_sign": 9.117,
"longitude_deg": 129.117,
"declination_deg": 20.516062,
"motion_state": "direct"
},
"Mercury": {
"id": "mercury",
"name": "Mercury",
"sign": "Pisces",
"sign_abbr": "Pis",
"sign_id": "pisces",
"pos": 21.973,
"abs_pos": 351.973,
"retrograde": true,
"speed": -0.428,
"is_stationary": false,
"latitude_deg": 3.294498,
"distance_au": 0.70680082,
"position_text": "21°58' Pisces Rx",
"degree_in_sign": 21.973,
"longitude_deg": 351.973,
"declination_deg": -0.156033,
"motion_state": "retrograde"
}
},
"astrology": {
"retrograde_bodies": ["Mercury"],
"stations": [],
"ingresses": [
{
"body": "Moon",
"sign": "Leo",
"degree_in_sign": 9.117,
"direction": "entering_sign"
}
],
"angular_bodies": [],
"notable_conditions": [
"retrograde:Mercury",
"ingress:Moon",
"moon_phase:waxing_gibbous"
],
"moon_phase": {
"name": "Waxing Gibbous",
"phase_angle_deg": 148.711,
"is_waxing": true
},
"moon_void_of_course": {
"is_void": false,
"definition": "No further exact major Moon aspect to Sun, Mercury, Venus, Mars, Jupiter, or Saturn before the Moon changes sign.",
"current_sign": "Leo",
"next_sign": "Virgo",
"sign_ingress_at": "2026-03-02T12:33:41Z",
"next_applying_aspect": {
"body": "mars",
"aspect": "opposition",
"exact_at": "2026-03-02T12:27:23Z"
}
}
}
}
}{
"meta": {
"start": "2026-03-01T00:00:00Z",
"end": "2026-03-31T00:00:00Z",
"step": "1d",
"rows": 31,
"bodies": ["Sun", "Moon", "Mercury"],
"format": "table",
"table_style": "grid",
"zodiac_type": "tropical",
"sidereal_ayanamsa": null,
"timezone": "UTC"
},
"display": {
"sign_style": "abbr",
"cell_format": "parts",
"motion_markers": {
"retrograde": "Rx",
"stationary": "S"
},
"columns": ["date", "weekday", "sidereal_time", "Sun", "Moon", "Mercury"]
},
"rows": [
{
"date": { "iso": "2026-03-01", "day": 1 },
"weekday": "Sun",
"sidereal_time": "10:35:16",
"Sun": {
"text": "10°24' Pis",
"degree_text": "10°24'",
"sign": "Pisces",
"sign_abbr": "Pis",
"motion_marker": null,
"entered_sign": false,
"station": false
},
"Mercury": {
"text": "21°58' Pis Rx",
"degree_text": "21°58'",
"sign": "Pisces",
"sign_abbr": "Pis",
"motion_marker": "Rx",
"entered_sign": false,
"station": false
}
},
{
"date": { "iso": "2026-03-02", "day": 2 },
"weekday": "Mon",
"sidereal_time": "10:39:12",
"Sun": {
"text": "11°25' Pis",
"degree_text": "11°25'",
"sign": "Pisces",
"sign_abbr": "Pis",
"motion_marker": null,
"entered_sign": false,
"station": false
},
"Moon": {
"text": "22°53' Leo",
"degree_text": "22°53'",
"sign": "Leo",
"sign_abbr": "Leo",
"motion_marker": null,
"entered_sign": true,
"station": false
},
"Mercury": {
"text": "21°28' Pis Rx",
"degree_text": "21°28'",
"sign": "Pisces",
"sign_abbr": "Pis",
"motion_marker": "Rx",
"entered_sign": false,
"station": false
}
}
],
"raw_rows": [
{
"timestamp": "2026-03-01T00:00:00Z",
"bodies": {
"Sun": {
"abs_pos": 340.406,
"degree_in_sign": 10.406,
"declination_deg": -7.665505,
"speed": 1.0037
},
"Moon": {
"abs_pos": 129.117,
"degree_in_sign": 9.117,
"declination_deg": 20.516062,
"speed": 13.8619
},
"Mercury": {
"abs_pos": 351.973,
"degree_in_sign": 21.973,
"declination_deg": -0.156033,
"speed": -0.428
}
}
}
]
}FAQ
Общие вопросы об эфемеридах западной астрологии API, ежемесячных планетарных таблицах, данных об отсутствии курса Moon и поддерживаемых вариантах расчета.
Что такое астрологическая эфемерида API?
Астрологический эфемерид API возвращает положения планет на определенную дату и время или в диапазоне дат. Эта эндпоинт вычисляет положения тропического или сидерического зодиака для планет, Moon, узлов, астероидов, углов, домов, аспектов, неподвижных звезд и таблиц эфемерид в месячном стиле.
Могу ли я получить ежемесячную таблицу планетарных эфемерид?
Да. Используйте GET /api/v1/ephemeris с format=table и table_style=grid, чтобы возвращать одну строку в день и один столбец для каждого запрошенного тела. Режим сетки предназначен для ежемесячных астрологических календарей и ограничен 31 строкой на запрос.
Поддерживает ли эндпоинт эфемерид Moon void of course?
Да. Установите include_moon_void_of_course=true, чтобы добавить астрологию.moon_void_of_course для каждого снимка. Ответ включает информацию о том, является ли Moon недействительным, о следующем входе знака Moon и о следующем применении основного аспекта Moon перед входом, если таковой существует.
Насколько точны положения планет?
Бэкэнд использует точные астрономические расчеты планетарной долготы, широты, скорости, ретроградного состояния, склонения, неподвижных звезд и данных о домах, где это применимо. Результаты включают метаданные юлианского дня, чтобы приложения могли проверять контекст вычислений.
Могу ли я запросить данные тропических и сидерических эфемерид?
Да. Используйте zodiac_type=тропический для западных тропических эфемерид по умолчанию или zodiac_type=сидерический с sidereal_ayanamsa, например, лахири, для сидерических расчетов.
Могу ли я включить дома и углы в запрос эфемерид?
Да. Отправьте широту и долготу или определимый город на POST, затем включите include_houses или include_angles. При наличии координат дома и углы включаются автоматически, если они не отключены явно.
Какие временные шаги поддерживаются?
Эндпоинт поддерживает целые минутные, часовые и дневные интервалы, такие как 1 метр, 5 минут, 15 минут, 1 час, 6 часов, 1 день и 7 дней. Диапазоны минутного уровня ограничены 1440 строками, а таблицы сетки — 31 строкой.
Могу ли я рассчитать аспекты в ответе эфемерид?
Да. Установите include_aspects=true, чтобы включить данные аспекта моментального снимка. Установите include_minor_aspects=true, если вам также нужны второстепенные аспекты помимо набора основных аспектов.
Какие планеты и астрологические точки я могу запросить?
Эндпоинт поддерживает Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, Chiron, Pholus, Ceres, Pallas, Juno, Vesta, Mean Node, True Node, Lilith, True Lilith, Ascendant, MC, Vertex и Part of Fortune.
Могу ли я использовать эфемериды API для астрологических приложений и календарей?
Да. JSON format подходит для логики приложения, а строки, столбцы и таблицы таблиц подходят для астрологических календарей, информационных панелей, экспорта и отображения эфемерид по месяцам.