万年历 API · 干支查算

GET /api/wannianli/query

返回字段与调用示例

返回字段（data）

错误码

调用示例（curl · API 密钥免登录，按地区选出生地）

推荐写法：出生地只传地区统一编号 region_code，一个纯 ASCII 参数即锁定全球任意最小单位地区，免中文编码、免同名歧义。例：CN-00246 = 中国·湖南省·张家界市、CN-00001 = 中国·上海市·上海市。传了 region_code 就不必再传 province / region / lon。

curl -G "https://www.yuanka.com.cn/api/wannianli/query" \
  --data-urlencode "date=2026-09-19" \
  --data-urlencode "hour=04:30" \
  --data-urlencode "region_code=CN-00246" \
  -H "Authorization: Bearer <你的API密钥>"

若要按汉字省名 / 市名调用（province + region），请确保终端编码为 UTF-8（Linux / macOS / Git Bash 等）：Windows 传统 cmd 默认 GBK 代码页，中文参数会编码错乱并静默失效——接口照样返回 code=0，但 data.lon 为 null、地区未生效，真太阳时不会修正。另外 cmd 的续行符是 ^ 而不是 \，请把命令写成一行，否则参数会被吞掉、-H 请求头可能一起失效（表现为误报 401 请先登录）。这类环境请直接用上面的 region_code。

curl -G "https://www.yuanka.com.cn/api/wannianli/query" \
  --data-urlencode "date=2026-09-19" \
  --data-urlencode "hour=04:30" \
  --data-urlencode "province=浙江省" \
  --data-urlencode "region=杭州市" \
  -H "Authorization: Bearer <你的API密钥>"

返回结果示例（真实响应 · 杭州 CN-00219 2026-09-19 04:30；其中 used / limit / remain 为示意值）

{
  "code": 0,
  "data": {
    "auth": "api_key",
    "mode": "solar",
    "input": "2026-09-19",
    "date": "2026-09-19",
    "week": "周六",
    "lunar": {
      "lunarYear": 2026, "lunarMonth": 8, "lunarDay": 9, "isLeap": false,
      "lunarMonthCn": "八月", "lunarDayCn": "初九",
      "lunarYearCn": "2026年",
      "lunarFullCn": "2026年八月初九", "zodiac": "马"
    },
    "bazi": {
      "year":  { "gan": 2, "zhi": 6, "name": "丙午" },
      "month": { "gan": 3, "zhi": 9, "name": "丁酉" },
      "day":   { "gan": 2, "zhi": 8, "name": "丙申" },
      "hour":  { "gan": 6, "zhi": 2, "name": "庚寅" }
    },
    "lon": 120.16, "lonFrom": "region",
    "region": { "code": "CN-00219", "province": "浙江省", "name": "杭州市", "lon": 120.16, "lat": 30.29 },
    "duty": "丙申｜管仲日君",
    "used": 10, "limit": 500, "remain": 490,
    "disclaimer": "以上干支历法信息仅为古代干支纪日传统文化与仙侠文学创作语境下的意象参考，不作吉凶祸福之实际判定。"
  }
}

示例按「2026-09-19 04:30 出生于浙江省 杭州市」换算：hour 传具体钟点（HH:MM）才触发真太阳时修正；出生地可传 region_code=CN-00219（推荐，等价于杭州），也可传 province + region 汉字由系统换算，或只传 province 按该省省会默认，或用 lon 手填经度。注意：手填经度不含国家信息，出生地时区由经纬度就近推断，中国西部这类「时区与经度并不对应」的出生地建议仍用 region_code。（优先级：region_code → lon → province+region）。若仍要用汉字，推荐 --data-urlencode 方式；curl 对 URL 里直接写中文可能报 Bad hostname，请用 -G --data-urlencode 形式或百分号编码——这也是改用地区编号的原因之一。亦可在 api_key 查询参数里传密钥：

curl -G "https://www.yuanka.com.cn/api/wannianli/query" \
  --data-urlencode "date=2026-09-19" \
  --data-urlencode "hour=04:30" \
  --data-urlencode "province=浙江省" \
  --data-urlencode "region=杭州市" \
  --data-urlencode "api_key=<你的API密钥>"

调用示例（curl · 登录会话，手填经度）

curl -b "YCGSESSID=你的会话" \
  "https://www.yuanka.com.cn/api/wannianli/query?date=2026-09-19&hour=04:30&lon=120.16"

农历调用示例（2023 闰二月初一，只传省份按省会默认）

curl -G "https://www.yuanka.com.cn/api/wannianli/query" \
  --data-urlencode "lunar_year=2023" \
  --data-urlencode "lunar_month=2" \
  --data-urlencode "lunar_day=1" \
  --data-urlencode "lunar_leap=1" \
  --data-urlencode "hour=04:30" \
  --data-urlencode "province=广东省" \
  -H "Authorization: Bearer <你的API密钥>"

使用提示：① 想得到结合出生地精确的时柱，hour 务必传具体钟点（HH:MM，24 小时制）；只传 午 这类时辰名时按该时辰直接取时柱、不做经度修正；留空或传非法值时 bazi.hour.name 返回 ??（时辰不详）。② 出生地优先级 region_code → lon → province+region，推荐传 region_code（地区统一编号，纯 ASCII、覆盖全球城市、免中文编码与同名歧义，编号表可下载）；或传 province + region（系统查城市经度，province 用于同名消歧，只传 province 按省会默认）；lon 手填经度请慎用——它不含国家信息，出生地时区要由经纬度就近推断，中国西部这类「时区与经度并不对应」的出生地会算错时柱。同时传入时以优先级高者为准。③ 返回 data.bazi 的四柱即经真太阳时校正后结果；建议核对 data.region.code 是否等于你传入的编号（用 province+region 汉字解析时 code 为空字符串，属正常），以确认地区解析无误。④ 传了 region_code 却查无此编号会直接返回 400，不会静默按别处计算。

鉴权：① 会话方式（须以登录会员的会话 Cookie 调用）；② API 密钥方式（免登录，密钥需在会员中心生成，可按 IP 白名单限制来源，若配置了白名单则仅允许白名单内的来源 IP 调用）。两种方式均计入当日额度，超额返回 429；配置了白名单的密钥若来源 IP 不在名单内，返回 403。