八字真太阳时校正 API 文档

八字真太阳时校正 API

显示民用时、地方平太阳时、经度修正、均时差，以及相对和绝对真太阳时，便于审计八字时柱使用的时间。

POST /api/v1/chinese/bazi/time-correction

中文响应与兼容性约定

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

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

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

请求参数

字段

year / month / day

类型

integer

必填

是

说明

待校正的公历日期。

字段

hour / minute

类型

integer

必填

否

说明

民用钟表时间。

字段

lat / lng

类型

float

必填

否

说明

地点坐标；也可提供 city。

字段

tz_str

类型

string

必填

否

说明

IANA 时区；AUTO 会按地点与历史日期解析。

字段

lang

类型

string

必填

否

说明

设置 zh-CN 返回简体中文说明。

字段	类型	必填	说明
year / month / day	integer	是	待校正的公历日期。
hour / minute	integer	否	民用钟表时间。
lat / lng	float	否	地点坐标；也可提供 city。
tz_str	string	否	IANA 时区；AUTO 会按地点与历史日期解析。
lang	string	否	设置 zh-CN 返回简体中文说明。

请求示例

curl -X POST "https://api.freeastroapi.com/api/v1/chinese/bazi/time-correction" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "year": 1990,
    "month": 5,
    "day": 17,
    "hour": 14,
    "minute": 30,
    "lat": 31.2304,
    "lng": 121.4737,
    "tz_str": "Asia/Shanghai",
    "lang": "zh-CN"
  }'

响应示例

{
  "civil_time": "1990-05-17T14:30:00",
  "lmt": "1990-05-17T13:35:53.688000",
  "true_solar_relative": "1990-05-17T14:39:34.186987",
  "true_solar_absolute": "1990-05-17T13:39:34.186987",
  "equation_of_time_minutes": 3.67,
  "longitude_correction_minutes": 5.89,
  "standard_meridian": 120.0,
  "resolved_timezone": "Asia/Shanghai",
  "dst_offset_hours": 1.0,
  "modalities": {
    "civil": "民用钟表时间。经过标准化，但不考虑当地太阳时。",
    "true_solar": "相对真太阳时。修正地点在时区内的位置，同时保留该时辰的时间感。",
    "true_solar_absolute": "绝对日晷时。根据经度与地球公转计算纯太阳时，完全忽略时区。"
  }
}

模式说明

civil 是民用钟表时间；true_solar 按时区中央经线做相对修正；true_solar_absolute 以经度和均时差计算绝对日晷时间。这些枚举值属于稳定 API 合约，不随语言变化。