Эфемериды

POST/api/v1/ephemeris/calculate

Запрос положений планет по одной временной метке или полному диапазону дат с настраиваемыми шагами. Метаданные астрологического уровня, дополнительные аспекты и вывод таблиц, предназначенные для календарей, экспорта, и ежемесячные представления эфемерид.

Полный URL

https://api.freeastroapi.com/api/v1/ephemeris/calculate

Удобство GET /api/v1/ephemeris псевдоним также доступен для рабочих процессов со строкой запроса.

Пример ежемесячной сетки

Это самый ясный способ понять, что table_style=сетка возвращает: одна строка в день, один столбец на тело, с отформатированными позициями, готовыми для календаря внешнего интерфейса или представления экспорта.

DateWeekdaySid.tSunMoonMercuryVenusMarsJupiterSaturn
1Sun10:35:1610°24' Pis09°07' Leo21°58' Pis Rx23°13' Pis28°45' Aqu15°15' Can Rx01°43' Ari
2Mon10:39:1211°25' Pis22°53' Leo21°28' Pis Rx24°28' Pis29°32' Aqu15°13' Can Rx01°51' Ari
3Tue10:43:0912°25' Pis06°25' Vir20°50' Pis Rx25°42' Pis00°19' Pis15°12' Can Rx01°58' Ari
4Wed10:47:0513°25' Pis19°43' Vir20°05' Pis Rx26°57' Pis01°06' Pis15°10' Can Rx02°05' Ari
5Thu10:51:0214°25' Pis02°44' Lib19°15' Pis Rx28°12' Pis01°54' Pis15°09' Can Rx02°12' Ari
6Fri10:54:5915°25' Pis15°28' Lib18°19' Pis Rx29°27' Pis02°41' Pis15°08' Can Rx02°20' Ari
7Sat10:58:5516°25' Pis27°56' Lib17°20' Pis Rx00°41' Ari03°28' Pis15°07' Can Rx02°27' Ari
8Sun11:02:5217°25' Pis10°10' Sco16°20' Pis Rx01°56' Ari04°16' Pis15°06' Can Rx02°34' Ari
9Mon11:06:4818°25' Pis22°14' Sco15°19' Pis Rx03°10' Ari05°03' Pis15°06' Can Rx02°41' Ari
10Tue11:10:4519°25' Pis04°10' Sag14°19' Pis Rx04°25' Ari05°50' Pis15°05' Can Rx02°49' Ari
11Wed11:14:4120°25' Pis16°03' Sag13°22' Pis Rx05°40' Ari06°37' Pis15°05' Can Rx02°56' Ari
12Thu11:18:3821°25' Pis27°57' Sag12°28' Pis Rx06°54' Ari07°25' Pis15°05' Can03°04' Ari
13Fri11:22:3422°25' Pis09°57' Cap11°38' Pis Rx08°09' Ari08°12' Pis15°06' Can03°11' Ari
14Sat11:26:3123°25' Pis22°09' Cap10°53' Pis Rx09°23' Ari08°59' Pis15°06' Can03°18' Ari
15Sun11:30:2824°25' Pis04°35' Aqu10°14' Pis Rx10°38' Ari09°46' Pis15°07' Can03°26' Ari
16Mon11:34:2425°24' Pis17°19' Aqu09°41' Pis Rx11°52' Ari10°34' Pis15°08' Can03°33' Ari
17Tue11:38:2126°24' Pis00°24' Pis09°14' Pis Rx13°06' Ari11°21' Pis15°09' Can03°41' Ari
18Wed11:42:1727°24' Pis13°51' Pis08°54' Pis Rx14°21' Ari12°08' Pis15°10' Can03°48' Ari
19Thu11:46:1428°24' Pis27°39' Pis08°39' Pis Rx15°35' Ari12°55' Pis15°11' Can03°56' Ari
20Fri11:50:1029°23' Pis11°44' Ari08°31' Pis Rx16°49' Ari13°42' Pis15°13' Can04°03' Ari
21Sat11:54:0700°23' Ari26°03' Ari08°30' Pis18°04' Ari14°30' Pis15°15' Can04°10' Ari
22Sun11:58:0301°23' Ari10°30' Tau08°34' Pis19°18' Ari15°17' Pis15°17' Can04°18' Ari
23Mon12:02:0002°22' Ari24°59' Tau08°43' Pis20°32' Ari16°04' Pis15°19' Can04°25' Ari
24Tue12:05:5703°22' Ari09°26' Gem08°58' Pis21°46' Ari16°51' Pis15°21' Can04°33' Ari
25Wed12:09:5304°21' Ari23°45' Gem09°18' Pis23°00' Ari17°38' Pis15°24' Can04°40' Ari
26Thu12:13:5005°21' Ari07°55' Can09°43' Pis24°15' Ari18°25' Pis15°27' Can04°48' Ari
27Fri12:17:4606°20' Ari21°52' Can10°13' Pis25°29' Ari19°12' Pis15°30' Can04°55' Ari
28Sat12:21:4307°19' Ari05°36' Leo10°47' Pis26°43' Ari19°59' Pis15°33' Can05°03' Ari
29Sun12:25:3908°19' Ari19°08' Leo11°25' Pis27°57' Ari20°46' Pis15°36' Can05°10' Ari
30Mon12:29:3609°18' Ari02°27' Vir12°07' Pis29°11' Ari21°33' Pis15°39' Can05°18' Ari
31Tue12:33:3210°17' Ari15°34' Vir12°53' Pis00°25' Tau22°20' Pis15°43' Can05°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"

Ключевые параметры

ParameterTypeReqDescription
startstringДаТребуемая дата и время ISO. Если указан только start, эндпоинт возвращает один снимок на этот момент.
endstringНетНеобязательная дата и время ISO для запросов диапазона. Для начала должно быть больше или равно.
stepstringНетЦелый минутный/часовой/дневной интервал, например 1 м, 5 м, 15 м, 1 ч, 6 ч, 1 д или 7 дн. По умолчанию: 1д.
citystringНетТолько POST. Работает как natal: если указано без широты и долготы, серверная часть автоматически определяет координаты.
latfloatНетШирота. Если указаны широта и долгота, они переопределяют поиск города и используются напрямую.
lngfloatНетДолгота. Требуется вместе с lat для прямых запросов координат.
tz_strstringНетСтрока часового пояса или AUTO. AUTO использует разрешенные координаты и дату для определения часового пояса.
bodiesarray[str] | csvНетЗапрошенные тела или точки. Принимает массив POST или строку GET, разделенную запятыми.
formatstringНетjson или таблицу. По умолчанию: json.
response_modestringНетПсевдоним формата. Полезно для запросов к таблицам в рабочих процессах обработки строк запросов.
table_stylestringНетстроки, столбцы или сетка. Сетка — это выходные данные календаря в стиле месяца.
zodiac_typestringНетtropical (по умолчанию) или sidereal.
sidereal_ayanamsastringНетИспользуется только тогда, когда zodiac_type=звездный. Соответствует натальным соглашениям об именах.
house_systemstringНетСистема домов, используемая при расчете домов или углов. По умолчанию: Плацидус.
include_aspectsbooleanНетЕсли true, включает данные аспекта для каждого снимка.
include_minor_aspectsbooleanНетЕсли true, аспекты расширяются, включая второстепенные типы аспектов.
include_moon_void_of_coursebooleanНетЕсли true, добавляется астрология.moon_void_of_course с текущим состоянием VOC, следующим входом знака Moon и следующим применением основного аспекта Moon перед входом, если он существует.
include_fixed_starsbooleanНетЕсли true, возвращает набор астрологических фиксированных звезд по умолчанию в fixed_stars для каждого снимка.
fixed_starsarray[str] | csvНетНеобязательный явный список фиксированных звезд. Принимает массив POST или строку GET, разделенную запятыми, например Spica,Regulus.
include_housesbooleanНетЕсли true, возвращает дома. Включается автоматически, когда координаты доступны, если явно не установлено значение false.
include_anglesbooleanНетЕсли true, возвращает данные восходящего/MC/связанного угла. Включается автоматически, когда координаты доступны, если явно не установлено значение false.

Поведение местоположения

  • Рекомендуемый поток: используйте Поиск города, дайте пользователю выбрать точный результат, а затем отправьте lat, lng, и в идеале tz_str.
  • city on POST /api/v1/ephemeris/calculate это запасной вариант для удобства. Если вы отправляете только город, серверная часть автоматически определяет координаты.
  • Если у вас уже есть координаты, пришлите их. Не отправляйте обратно только название города после поиска города, если только вы не хотите, чтобы серверная часть выполнила второй поиск.
  • При наличии координат дома и углы включаются автоматически, если вы явно не отключите их.

Пределы диапазона

  • table_style=сетка предназначен для отображения в виде месяца и ограничен 31 ряды. Большие запросы возвращаются 400 grid_range_too_large.
  • Используйте 1h и 1d для стандартных таблиц и экспорта.
  • Используйте мельчайшие шаги, такие как 1m или 5m только для работы по точному времени.
  • Диапазоны минутного уровня ограничены 1440 ряды, примерно 24h at 1m. Большие запросы возвращаются 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 подходит для логики приложения, а строки, столбцы и таблицы таблиц подходят для астрологических календарей, информационных панелей, экспорта и отображения эфемерид по месяцам.