星河API星河 API 观测平台

万年历

GET 需密钥

万年历 / 农历查询：输入公历日期（缺省为今天），返回星期、农历年月日、干支生肖等常规日历数据；传 detail=1 可获取干支三柱（含纳音）、节气、宜忌、神煞、建除十二值神、黄黑道、六曜、月相、星座、节日与法定假日等扩展数据。

调用地址

https://api.shurans.cn/api/calendar

调用方式

GET

# 请求头携带密钥
Authorization: Bearer <你的密钥>

请求参数

参数必填示例说明
date 可选 2026-10-16 公历日期，格式 YYYY-MM-DD；缺省为今天
detail 可选 1 是否返回扩展数据：1 或 true 开启；0 或 false / 缺省仅返回常规农历日期数据

响应示例

{
    "code": 200,
    "message": "ok",
    "data": {
        "date": "2026-10-16",
        "solar": {
            "year": 2026,
            "month": 10,
            "day": 16,
            "week": 5,
            "week_name": "星期五"
        },
        "lunar": {
            "year": "二〇二六",
            "year_name": "丙午",
            "zodiac": "马",
            "month": 9,
            "is_leap_month": false,
            "month_name": "九月",
            "day": 7,
            "day_name": "初七"
        },
        "day_cycle": "癸亥",
        "detail": {
            "pillars": {
                "year": { "name": "丙午", "sound": "天河水" },
                "month": { "name": "戊戌", "sound": "平地木" },
                "day": { "name": "癸亥", "sound": "大海水" }
            },
            "term": { "name": "寒露", "start": "2026-10-08", "day": 9 },
            "yi": ["祭祀", "开光", "出行", "解除", "理发", "伐木"],
            "ji": ["嫁娶", "安葬", "行丧", "词讼", "造桥", "作灶"],
            "gods": [
                { "name": "四相", "luck": "吉" },
                { "name": "玉堂", "luck": "吉" },
                { "name": "劫煞", "luck": "凶" }
            ],
            "duty": "除",
            "twelve_star": { "name": "玉堂", "ecliptic": "黄道" },
            "six_star": "先负",
            "phase": "蛾眉月",
            "constellation": "天秤座",
            "festival": null,
            "lunar_festival": null,
            "legal_holiday": null
        }
    },
    "meta": { "request_id": "7214361835712ec46e74081384fc82be" }
}

响应字段说明

字段说明
data.date 查询的公历日期（YYYY-MM-DD，缺省 date 时为当天的展开值）
data.solar.year/month/day 公历年 / 月 / 日（数字）
data.solar.week 星期索引：0 周日、1–6 周一至周六
data.solar.week_name 星期名称，如「星期五」
data.lunar.year 农历年份中文数字，如「二〇二六」（以正月初一换年）
data.lunar.year_name 农历年干支，如「丙午」
data.lunar.zodiac 生肖，如「马」
data.lunar.month 农历月份数字（1–12）
data.lunar.is_leap_month 是否闰月
data.lunar.month_name 农历月名称，闰月带「闰」前缀，如「闰六月」
data.lunar.day 农历日数字（1–30）
data.lunar.day_name 农历日名称，如「初七」「十五」
data.day_cycle 当日干支（干支纪日），如「癸亥」
data.detail.pillars.* 干支三柱（仅 detail=1）：year / month / day 年柱 / 月柱 / 日柱，各含 name 干支与 sound 纳音；按干支历划分（立春换年、节气换月）
data.detail.term 节气（仅 detail=1）：name 节气名、start 节气首日、day 处于该节气第几天（从 1 起）
data.detail.yi / ji 宜 / 忌事项数组（仅 detail=1，传统黄历推算）
data.detail.gods 神煞数组（仅 detail=1），每项含 name 名称与 luck 吉凶
data.detail.duty 建除十二值神，如「除」（仅 detail=1）
data.detail.twelve_star 黄黑道十二神（仅 detail=1）：name 如「玉堂」、ecliptic 黄道 / 黑道
data.detail.six_star 六曜，如「先负」（仅 detail=1）
data.detail.phase 月相，如「蛾眉月」（仅 detail=1）
data.detail.constellation 星座，如「天秤座」（仅 detail=1）
data.detail.festival 公历节日名，无则为 null（仅 detail=1）
data.detail.lunar_festival 农历传统节日名（春节 / 端午节 / 除夕等），无则为 null（仅 detail=1）
data.detail.legal_holiday 法定假日：name 名称、work 是否调休补班日；非法定假日为 null（仅 detail=1）
meta.request_id 本次请求的追踪 ID（32 位十六进制），同时随 X-Request-Id 响应头返回

© 2026 星河 API