Хронология фаз Луны
Хронология фаз Луны
/api/v1/moon/monthПолучите снимки Луны за полный месяц, а также дополнительные интервалы знаков и входные события. Эта конечная точка предназначена для лунных календарей, представлений временной шкалы и визуализаций пользовательского интерфейса, которым требуется один запрос вместо одного вызова в день.
Полный URL-адрес
https://api.freeastroapi.com/api/v1/moon/monthПлан доступа
Эта конечная точка доступна на Entry and High планы. Бесплатные ключи получают структурированное 403 ответ с entry_or_high_plan_required.
Daily /api/v1/moon/phase остается правильным выбором для облегченных проверок free-tier.
Поведение календаря
Конечная точка месяца по умолчанию рассчитывает календарь в формате UTC. Укажите местоположение через city or lat/lon для поведения local-calendar и данных observer-specific. Каждый предмет в days получает calendar_date, в то время как это timestamp остается в UTC. Без контекста местоположения конечная точка возвращается к календарным дням UTC.
- Поиск города: Pass
cityкогда вам нужно то же удобство, что и конечная точка single-date Moon. - Местные полночи: With
cityorlat/lon, выборка месяца производится в полночь по местному времени в разрешенном часовом поясе. - Обработка часового пояса:
tz_strпо умолчаниюAUTO, который определяет часовой пояс изcityorlat/lon. Вы также можете указать явный часовой пояс IANA, напримерEurope/Paris. - дни[] предназначен для ежедневных снимков Луны.
- sign_timeline[] предназначен для интервальных полос на временной шкале.
- проникает[] предназначен для маркеров событий, таких как
Virgo -> Libra.
Параметры запроса
| Parameter | Type | Required | Description |
|---|---|---|---|
| year | integer | Yes | Календарный год для извлечения, например 2026. |
| month | integer | Yes | Календарный месяц от 1 до 12. |
| city | string | No | Название города для поиска координат и разрешения часового пояса (альтернативно широте/долготе). |
| lat | float | No | Широта для выборки local-calendar и данных observer-specific. По умолчанию: Нет. |
| lon | float | No | Долгота для выборки local-calendar и данных observer-specific. По умолчанию: Нет. |
| tz_str | string | No | Строка часового пояса для выборки местного календаря и простой интерпретации даты и времени. По умолчанию: AUTO. |
| include_zodiac | boolean | No | Включите тропический знак зодиака Луны на каждый день. По умолчанию: false. |
| include_visuals | boolean | No | Включите луну SVG и соотношение теней для каждого дня месяца. По умолчанию: false. |
| include_special | boolean | No | Включите специальные метки луны для каждого дня, например «суперлуние» или «урожайная луна». По умолчанию: false. |
| include_eclipse | boolean | No | Включите проверки затмений в каждую ежедневную строку. По умолчанию: false. |
| include_forecast | boolean | No | Включите прогнозы next-phase и next-event на день. По умолчанию: false. |
| include_traditional_moon | boolean | No | Включите традиционный блок имен full-moon для каждого дня. По умолчанию: false. |
| include_sign_timeline | boolean | No | Возвращает интервалы знаков top-level и маркеры входа за месяц. По умолчанию: false. |
| style_moon_color | string | No | Шестнадцатеричный цвет для освещенной лунной заливки внутри ежедневных ответов SVG. По умолчанию: #E0E0E0. |
| style_shadow_color | string | No | Шестнадцатеричный цвет для заливки теней внутри ежедневных ответов SVG. По умолчанию: #1A1A1A. |
Семантика временной шкалы
Сегменты в sign_timeline include duration_hours and duration_minutesпоэтому интерфейс может определять размеры полос без дополнительных математических вычислений. Переходные ряды также включают в себя next_sign, next_sign_idи ready-made label.
Последний сегмент месяца не предполагает будущего входа. Он возвращает next_sign: null, next_sign_id: null, и label: null, пока continues_to_next_month сообщает вам, что интервал продолжается за пределами видимого диапазона.
Пример кода
curl -X GET "https://api.freeastroapi.com/api/v1/moon/month?year=2026&month=4&city=Paris&tz_str=AUTO&include_zodiac=true&include_visuals=true&include_traditional_moon=true&include_sign_timeline=true" \
-H "x-api-key: YOUR_API_KEY"Данные ответа
Этот пример основан на реальном сохраненном ответе для Парижа за апрель 2026 года. Структура и ценности реальны; полезная нагрузка SVG сокращается до <svg>...</svg> для читабельности.
{
"year": 2026,
"month": 4,
"month_name": "April",
"days_in_month": 30,
"calendar_basis": "local",
"calendar_timezone": "Europe/Paris",
"sign_timeline": [
{
"sign": "Virgo",
"sign_id": "virgo",
"starts_at": "2026-03-31T22:00:00Z",
"ends_at": "2026-04-01T02:51:05Z",
"starts_at_local": "2026-04-01T00:00:00+02:00",
"ends_at_local": "2026-04-01T04:51:05+02:00",
"duration_hours": 4.85,
"duration_minutes": 291,
"next_sign": "Libra",
"next_sign_id": "libra",
"label": "Virgo -> Libra",
"continues_from_previous_month": true,
"continues_to_next_month": false
}
],
"ingresses": [
{
"from_sign": "Virgo",
"from_sign_id": "virgo",
"to_sign": "Libra",
"to_sign_id": "libra",
"at": "2026-04-01T02:51:05Z",
"at_local": "2026-04-01T04:51:05+02:00",
"label": "Virgo -> Libra"
}
],
"days": [
{
"calendar_date": "2026-04-01",
"timestamp": "2026-03-31T22:00:00+00:00",
"phase": {
"name": "Waning Gibbous",
"phase_angle_deg": 214.63,
"illumination": 0.91,
"age_days": 17.6,
"distance_km": 384120,
"is_waxing": false
},
"zodiac": {
"sign": "Virgo",
"sign_id": "virgo",
"degree": 27.88,
"zodiac_type": "tropical"
},
"moon_visual": {
"type": "svg",
"svg": "<svg>...</svg>",
"shadow_ratio": 0.09,
"waxing": false
},
"traditional_moon": {
"name": "Pink Moon",
"naming_system": "north_american_traditional",
"month": "April",
"applies_to_full_moon_at": "2026-04-02T02:46:09Z",
"is_current_full_moon": false
}
}
]
}Лучшие варианты использования
- Создавайте лунные календари month-grid с помощью одного звонка вместо 28–31 ежедневного запроса.
- Визуализируйте временные шкалы sign-ingress, используя
sign_timelineplusingresses. - Прикрепите значки луны SVG к каждому дню, включив
include_visuals=true. - Объедините ежедневный астрологический контекст с отображением временной шкалы для приложений, информационных панелей и планировщиков для печати.