天文事件API文档

天文事件接口：按订阅返回月相精确时刻、朔望、日月食、月掩星、升落表、偕日升落等天文事件。请求中 events 里写哪项就算哪项。时间均为 ISO 8601 带时区偏移，天体名为全大写。

基本信息

参数值
Base URLhttps://chart.12sign.top
接口URL/spc/astro_events
请求方式POST
Content-Typeapplication/json

请求参数

1. 基础参数（必需）

参数名类型必选说明
data.datetimestring是基准时刻，格式：YYYY-MM-DD HH:MM:SS
data.latnumber是地点纬度（升落/偕日升落用）
data.lonnumber是地点经度
data.tznumber/string是地点时区，如 8 表示UTC+8

2. events 订阅项（至少传一项）

订阅项子参数说明
moon_aspect_timeplanet（默认 SUN）、aspect（度数，默认 0）、forward（默认 true）月亮与指定行星成指定相位的精确时刻
previous_lunation—基准时刻之前最近的朔望点
lunation_listdays（默认 30）基准时刻起 days 天内的新月/满月清单
rise_set_tablebody（默认 SUN）、days（默认 7）指定天体逐日升/落时刻表
first_visibilitybodies（默认 ["VENUS"]）、rising（默认 true）指定天体的偕日升/偕日落
solar_eclipse_listdays（默认 365）days 天内的日食清单
lunar_eclipse_listdays（默认 365）days 天内的月食清单
lunar_occultationsbody（默认 JUPITER）、days（默认 60）days 天内月亮掩指定行星的清单

天体名可选值（全大写）：SUN / MOON / MERCURY / VENUS / MARS / JUPITER / SATURN / URANUS / NEPTUNE / PLUTO / CHIRON

请求示例

{
    "data": {"datetime": "2026-10-19 12:00:00", "lat": 39.9, "lon": 116.4, "tz": 8},
    "events": {
        "moon_aspect_time": {"planet": "JUPITER", "aspect": 0, "forward": true},
        "previous_lunation": true,
        "lunation_list": {"days": 30},
        "rise_set_table": {"body": "SUN", "days": 2},
        "first_visibility": {"bodies": ["VENUS"], "rising": true},
        "lunar_occultations": {"body": "JUPITER", "days": 90}
    }
}

返回参数

每个订阅项对应 events 下同名字段，全部时间为 ISO 8601 带时区偏移：

字段类型说明
timestring基准时刻，ISO 8601 带时区偏移（与 data.tz 一致）
events.moon_aspect_timeobject{exact_time(精确时刻), residual_deg(求根残差, 度)}
events.previous_lunationobject{phase("新月"/"满月"), time, moon_longitude}
events.lunation_list[]object{phase, time, sun_longitude, moon_longitude}
events.rise_set_table[]object{date(YYYY-MM-DD), rise_time, set_time}（无升或无落时为 null）
events.first_visibility.{天体}object{first_time, best_time, last_time}（无则为 null）
events.solar_eclipse_list[]object{kind("日食"), detail(食型), time}
events.lunar_eclipse_list[]object{kind("月食"), detail(食型), time, umbra_magnitude}
events.lunar_occultations[]object{body(被掩天体, 全大写), time}
errorsobject计算失败的订阅项及原因（全部成功时无此字段）

返回示例（节选）

{
    "success": true,
    "time": "2026-10-19T12:00:00+08:00",
    "events": {
        "moon_aspect_time": {"exact_time": "2026-11-03T06:50:34+08:00", "residual_deg": -1.1e-10},
        "previous_lunation": {"phase": "新月", "time": "2026-10-10T23:50:05+08:00", "moon_longitude": 197.360674},
        "lunation_list": [
            {"phase": "满月", "time": "2026-10-26T12:11:49+08:00", "sun_longitude": 212.761886, "moon_longitude": 32.761886},
            ...
        ],
        "rise_set_table": [
            {"date": "2026-10-19", "rise_time": "2026-10-20T06:29:22+08:00", "set_time": "2026-10-19T17:30:00+08:00"},
            ...
        ],
        "first_visibility": {"VENUS": {"first_time": "2026-11-01T06:30:45+08:00", "best_time": null, "last_time": null}},
        "lunar_occultations": [{"body": "JUPITER", "time": "2026-11-03T06:45:58+08:00"}, ...]
    }
}

使用说明

  • 所有时间均为 ISO 8601 带时区偏移字符串，时区与请求 data.tz 一致
  • 订阅项相互独立，某项失败不影响其他项（失败项记录在 errors）

Python 调用示例

import requests

response = requests.post('https://chart.12sign.top/spc/astro_events', json={
    "data": {"datetime": "2026-10-19 12:00:00", "lat": 39.9, "lon": 116.4, "tz": 8},
    "events": {
        "moon_aspect_time": {"planet": "JUPITER", "aspect": 0},
        "previous_lunation": True
    }
})
d = response.json()
print("月合木精确时刻:", d['events']['moon_aspect_time']['exact_time'])
print("前次朔望:", d['events']['previous_lunation'])

在线测试

请求地址：
https://chart.12sign.top/spc/astro_events
请求参数（JSON）：
返回结果：
点击"发送请求"后在此显示结果