当前四柱 API 文档 | FreeAstroAPI 中文说明

当前四柱 API

GET/api/v1/chinese/today

该接口返回当前时刻的年柱、月柱、日柱和时柱。这是一个快速、无参数的 endpoint，非常适合每日能量展示和快速参考。

中文响应与兼容性约定

使用 lang: "zh-CN"（POST 请求体）或?lang=zh-CN（GET 查询参数）请求简体中文响应。zh-Hans、zh 和zh_hans 也会归一化为同一书写语言。

面向用户的名称、说明、星期、五行、生肖、十神和错误消息会本地化。为避免破坏现有客户端， JSON 字段名、对象映射键、稳定 ID、错误代码、枚举值、模式值、ISO 时间戳、时区、库名、版本号和拼音保持不变。客户端应依据字段名与稳定代码处理逻辑，不要依据翻译后的显示文本建立判断。

例如 ten_god_distribution 内的Direct Wealth 等映射键属于兼容性标识，仍使用英文；页面标题、说明、描述和独立显示值会返回中文。

完整 URL

https://api.freeastroapi.com/api/v1/chinese/today

常见用例

每日能量检查

在仪表盘展示今天的五行能量。

快速参考

无需完整计算即可显示当前年/月/日柱。

兼容性预览

将当前四柱与用户的 natal chart 对比。

内容生成

基于四柱创建 daily horoscope-style 内容。

请求参数

这是一个没有参数的 GET 请求。只需要在 header 中提供 API key。响应基于请求时刻的 UTC 时间。

调用示例

curl -X GET "https://api.freeastroapi.com/api/v1/chinese/today?lang=zh-CN" \
 -H "x-api-key: YOUR_API_KEY"

响应数据

{
  "timestamp": "2024-12-31T10:30:00+00:00",
  "date": {
    "year": 2024,
    "month": 12,
    "day": 31
  },
  "pillars": [
    {
      "label": "年柱",
      "gan": "甲",
      "zhi": "辰",
      "gan_pinyin": "jiǎ",
      "zhi_pinyin": "chén",
      "gan_zhi": "甲辰",
      "element": {
        "stem": "木",
        "branch": "土"
      }
    },
    {
      "label": "月柱",
      "gan": "丙",
      "zhi": "子",
      "gan_pinyin": "bǐng",
      "zhi_pinyin": "zǐ",
      "gan_zhi": "丙子",
      "element": {
        "stem": "火",
        "branch": "水"
      }
    },
    {
      "label": "日柱",
      "gan": "戊",
      "zhi": "寅",
      "gan_pinyin": "wù",
      "zhi_pinyin": "yín",
      "gan_zhi": "戊寅",
      "element": {
        "stem": "土",
        "branch": "木"
      }
    },
    {
      "label": "时柱",
      "gan": "甲",
      "zhi": "巳",
      "gan_pinyin": "jiǎ",
      "zhi_pinyin": "sì",
      "gan_zhi": "甲巳",
      "element": {
        "stem": "木",
        "branch": "火"
      }
    }
  ],
  "day_master": {
    "stem": "戊",
    "pinyin": "wù",
    "element": "土",
    "polarity": "阳"
  },
  "elements_today": {
    "Wood": 2,
    "Fire": 2,
    "Earth": 2,
    "Metal": 0,
    "Water": 1
  }
}

📝 说明

时柱每两个中国时辰更新一次，约等于每两个钟表小时。
日柱按地方平太阳时在 23:00（晚上 11 点）切换，而不是午夜。
响应基于 UTC；请在应用中按本地时区调整展示。