本命盘
计算包含行星位置、宫位起点和相位的完整本命盘。
基本计算
bash
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",
"location": {
"latitude": 51.5074,
"longitude": -0.1278,
"timezone": "Europe/London"
}
}'参数
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
dateTime | string | 是 | 日期/时间，格式为 YYYY-MM-DDTHH:mm |
location.latitude | number | 是 | 纬度（-90 到 90） |
location.longitude | number | 是 | 经度（-180 到 180） |
location.timezone | string | 是 | IANA 时区标识符 |
houseSystem | string | 否 | 宫位系统（默认："placidus"） |
points | array | 否 | 要计算的天体点（参见下方可用天体点） |
orbs | object | 否 | 每种相位类型的自定义容许度（例如 { "conjunction": 8, "opposition": 6 }） |
language | string | 否 | 文本内容的语言代码（默认："en"） |
includeText | boolean | 否 | 包含解读文本（默认：false） |
includeReadableEntities | boolean | 否 | 包含人类可读的实体标题（默认：false） |
宫位系统
placidus— Placidus（默认）koch— Kochequal— 等宫制whole— 整体星座宫位制campanus— Campanusregiomontanus— Regiomontanusporphyry— Porphyry
响应
json
{
"data": {
"dateTime": "1990-06-15T12:30:00.000Z",
"points": {
"sun": {
"pointId": "sun",
"longitude": 84.5,
"sign": "gemini",
"signTitle": "Gemini",
"degreesInSign": 24.5,
"degreesInSignDms": [24, 30, 0],
"houseNumber": 10,
"houseId": "house-10",
"retrograde": false,
"pointTitle": "Sun",
"houseTitle": "10th House"
},
"moon": {
"pointId": "moon",
"longitude": 245.2,
"sign": "sagittarius",
"signTitle": "Sagittarius",
"degreesInSign": 5.2,
"degreesInSignDms": [5, 12, 0],
"houseNumber": 4,
"houseId": "house-4",
"retrograde": false,
"pointTitle": "Moon",
"houseTitle": "4th House"
}
},
"angles": {
"ascendant": {
"pointId": "ascendant",
"longitude": 180.5,
"degreesInSign": 0.5,
"degreesInSignDms": [0, 30, 0],
"sign": "libra"
},
"descendant": {
"pointId": "descendant",
"longitude": 0.5,
"degreesInSign": 0.5,
"degreesInSignDms": [0, 30, 0],
"sign": "aries"
},
"midheaven": {
"pointId": "midheaven",
"longitude": 270.2,
"degreesInSign": 0.2,
"degreesInSignDms": [0, 12, 0],
"sign": "capricorn"
},
"imumCoeli": {
"pointId": "imumCoeli",
"longitude": 90.2,
"degreesInSign": 0.2,
"degreesInSignDms": [0, 12, 0],
"sign": "cancer"
}
},
"houses": {
"cusps": [
{ "longitude": 180.5, "longitudeDms": { "degrees": 180, "minutes": 30, "seconds": 0 }, "sign": "libra" },
{ "longitude": 210.3, "longitudeDms": { "degrees": 210, "minutes": 18, "seconds": 0 }, "sign": "scorpio" }
],
"ascmc": [
{ "longitude": 180.5, "longitudeDms": { "degrees": 180, "minutes": 30, "seconds": 0 }, "sign": "libra" },
{ "longitude": 270.2, "longitudeDms": { "degrees": 270, "minutes": 12, "seconds": 0 }, "sign": "capricorn" }
]
},
"aspects": [
{
"pointA": "sun",
"pointB": "moon",
"aspect": "opposition",
"angle": 160.7,
"orb": 0.7,
"applying": false,
"pointATitle": "Sun",
"pointBTitle": "Moon",
"aspectTitle": "Opposition"
}
],
"chart": {
"url": "https://api.astroapi.cloud/api/chart2/natal.svg?..."
}
}
}宫位起点
每个宫位起点对象包含 longitude（黄道经度）、longitudeDms（度/分/秒）和 sign（星座 ID）。第一个宫位起点（cusps[0]）是上升点。ascmc 数组包含上升点、中天、ARMC 和天顶。
可用天体点
使用 points 参数选择要计算的天体点。如果省略，则使用默认集合。
默认天体点
sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, meanNode, trueNode, meanApogee, osculatingApog
所有可用天体点
| Point ID | 描述 |
|---|---|
sun | 太阳 |
moon | 月亮 |
mercury | 水星 |
venus | 金星 |
mars | 火星 |
jupiter | 木星 |
saturn | 土星 |
uranus | 天王星 |
neptune | 海王星 |
pluto | 冥王星 |
meanNode | 平均北交点 |
trueNode | 真实北交点 |
meanApogee | 平均黑月莉莉丝 |
osculatingApog | 真实黑月莉莉丝 |
chiron | 凯龙星 |
pholus | 福鲁斯 |
ceres | 谷神星 |
pallas | 智神星 |
juno | 婚神星 |
vesta | 灶神星 |
interpolatedLunarApogee | 插值月远地点（自然远地点） |
interpolatedLunarPerigee | 插值月近地点（普里阿普斯） |
earth | 地球 |
示例：仅计算太阳和火星
bash
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",
"location": {
"latitude": 51.5074,
"longitude": -0.1278,
"timezone": "Europe/London"
},
"points": ["sun", "mars"]
}'响应将在 points 对象中包含 sun 和 mars，并在 angles 对象中包含所有四个角度点：
json
{
"data": {
"points": {
"sun": { "pointId": "sun", "longitude": 84.5, "sign": "gemini", ... },
"mars": { "pointId": "mars", "longitude": 12.3, "sign": "aries", ... }
},
"angles": {
"ascendant": {
"pointId": "ascendant",
"longitude": 180.5,
"degreesInSign": 0.5,
"degreesInSignDms": [0, 30, 0],
"sign": "libra"
},
"descendant": { "pointId": "descendant", "longitude": 0.5, "sign": "aries", ... },
"midheaven": { "pointId": "midheaven", "longitude": 270.2, "sign": "capricorn", ... },
"imumCoeli": { "pointId": "imumCoeli", "longitude": 90.2, "sign": "cancer", ... }
},
"houses": { ... },
"aspects": [ ... ]
}
}角度点
所有四个角度点（ascendant、descendant、midheaven、imumCoeli）始终包含在 angles 对象中，与 points 参数无关。角度点源自宫位计算而非星历表，因此结构更简单（无速度或逆行数据）。houses 响应中的 ascmc 数组也始终包含原始角度经度。
月亮与太阳
计算月相、照明度、出升/落下时间和太阳位置数据。
POST /api/calc/moon-sun
bash
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 模块。
响应
json
{
"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 直接读取 NASA 的 JPL DE442 星历表，提供亚毫角秒精度的行星位置。有关数据源和修正的完整详情，请参阅计算精度页面。