本命盘

计算包含行星位置、宫位起点和相位的完整本命盘。

基本计算

curl -X POST "https://api.astroapi.cloud/api/calc/natal" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-06-15T14:30:00",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "timezone": "Europe/London"
  }'

参数

参数	类型	必填	描述
datetime	string	是	ISO 8601 日期时间
latitude	number	是	纬度（-90 到 90）
longitude	number	是	经度（-180 到 180）
timezone	string	是	IANA 时区标识符
houseSystem	string	否	宫位系统（默认："placidus"）

宫位系统

• placidus — Placidus（默认）
• koch — Koch
• equal — 等宫制
• whole — 整体星座宫位制
• campanus — Campanus
• regiomontanus — Regiomontanus
• porphyry — Porphyry

响应

{
  "data": {
    "type": "natal-chart",
    "attributes": {
      "planets": {
        "sun": { "longitude": 84.5, "latitude": 0, "sign": "gemini", "house": 10 },
        "moon": { "longitude": 245.2, "latitude": -3.1, "sign": "sagittarius", "house": 4 }
      },
      "houses": {
        "1": { "cusp": 180.5, "sign": "libra" },
        "2": { "cusp": 210.3, "sign": "scorpio" }
      },
      "aspects": [
        { "planet1": "sun", "planet2": "moon", "aspect": "opposition", "orb": 0.7 }
      ]
    }
  }
}

包含的天体

默认情况下，包含以下天体：

• 太阳、月亮
• 水星、金星、火星、木星、土星、天王星、海王星、冥王星
• 北交点、南交点
• 凯龙星、黑月莉莉丝
• 福点

月亮与太阳

计算月相、照明度、出升/落下时间和太阳位置数据。

POST /api/calc/moon-sun

curl -X POST "https://api.astroapi.cloud/api/calc/moon-sun" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "dateTime": "2024-06-15T12:00",
    "location": {
      "latitude": 52.37,
      "longitude": 4.89,
      "timezone": "Europe/Amsterdam"
    }
  }'

参数

参数	类型	必填	描述
dateTime	string	是	日期/时间，格式为 YYYY-MM-DDTHH:mm
location.latitude	number	是	纬度（-90 到 90）
location.longitude	number	是	经度（-180 到 180）
location.timezone	string	是	IANA 时区标识符

所需模块

此端点需要 module:moon 模块。

响应

{
  "data": {
    "moon": {
      "phaseName": "Waxing Gibbous",
      "phase": 0.62,
      "illumination": 0.78,
      "age": 9.2,
      "distance": 384400,
      "diameterDegrees": 0.52,
      "rise": "2024-06-15T14:23:00Z",
      "set": "2024-06-16T02:15:00Z"
    },
    "sun": {
      "rise": "2024-06-15T05:18:00Z",
      "set": "2024-06-15T22:03:00Z",
      "transit": "2024-06-15T13:40:00Z",
      "distance": 151820000,
      "diameterDegrees": 0.524,
      "twilight": {
        "civil": {
          "begin": "2024-06-15T04:38:00Z",
          "end": "2024-06-15T22:43:00Z"
        },
        "nautical": {
          "begin": "2024-06-15T03:32:00Z",
          "end": "2024-06-15T23:49:00Z"
        },
        "astronomical": {
          "begin": null,
          "end": null
        }
      }
    }
  }
}

计算精度

AstroAPI 使用瑞士星历表进行高精度计算。所有位置的计算精度达到角秒级别。

Beta：替代计算引擎

实验性功能

此功能处于 beta 阶段，可能存在精度问题。在生产环境中请谨慎使用。

AstroAPI 提供一种替代计算引擎（calc2），它使用自定义实现直接读取和评估瑞士星历表 SE1 数据文件，而非使用官方瑞士星历表库。该引擎针对速度进行了优化，可提供更快的响应时间。

要使用替代引擎，请在请求中包含 X-Use-Calc2 请求头：

curl -X POST "https://api.astroapi.cloud/api/calc/natal" \
  -H "X-Api-Key: your-api-key" \
  -H "X-Use-Calc2: true" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-06-15T14:30:00",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "timezone": "Europe/London"
  }'

主要区别

方面	标准引擎	Calc2 引擎（Beta）
实现方式	瑞士星历表	自定义实现
数据来源	SE1 星历文件	SE1 星历文件（相同数据）
速度	标准	可能更快
精度	角秒精度（参考标准）	可能有细微偏差
状态	生产就绪	Beta

何时使用 Calc2

• 推荐用于：速度优先于绝对精度的高流量应用程序
• 不推荐用于：需要最高天文精度的应用程序

已知限制

• 自定义实现可能与官方瑞士星历表库产生略微不同的结果
• 仍在积极开发和测试中
• 对于关键应用程序，应与标准引擎进行结果验证