返回中文文档
中国历法转换 API

中国历法转换 API

GET/api/v1/chinese/calendar/{date}

将公历日期转换为中国农历、干支、生肖、节气与节日数据，并分别返回春节和立春两种年份边界。

中文响应与兼容性约定

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

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

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

请求参数

字段
date
类型
string
必填
是
说明
路径日期，格式为 YYYY-MM-DD。
字段
lang
类型
string
必填
否
说明
响应语言。使用 zh-CN 获取简体中文；默认 en。
字段
x-api-key
类型
header
必填
是
说明
FreeAstroAPI 密钥。

请求示例

curl "https://api.freeastroapi.com/api/v1/chinese/calendar/2024-02-10?lang=zh-CN" \
  -H "x-api-key: YOUR_API_KEY"

中文响应示例

{
  "gregorian": {
    "date": "2024-02-10",
    "weekday": "星期六",
    "weekday_zh": "六"
  },
  "lunar": {
    "year": 2024,
    "month": 1,
    "day": 1,
    "is_leap_month": false,
    "year_name": "二〇二四",
    "month_name": "正月",
    "day_name": "初一"
  },
  "year_profiles": {
    "lunar_new_year": {
      "gan_zhi": "甲辰",
      "gan_pinyin": "jiǎ",
      "stem_element": "木",
      "branch_element": "土",
      "zodiac": "龙"
    }
  },
  "solar_terms": {
    "previous": {
      "name": "立春",
      "at": "2024-02-04T16:27:07+08:00",
      "timezone": "UTC+08:00",
      "kind": "jie"
    }
  },
  "metadata": {
    "calendar": "chinese_lunisolar",
    "calendar_library": "lunar-python",
    "calculation_standard": "通过农历 Python 库实现的寿星天文算法",
    "validated_date_range": {
      "authority": "香港天文台公历与农历对照表"
    }
  }
}

边界与错误

1582-10-05 至 1582-10-14 属于历史公历改革缺口，返回 HTTP 400。使用 lang=zh-CN 时，已知转换错误和鉴权错误会返回中文消息；code 等稳定错误标识保持英文。