赤纬
星盘是黄道上的一次投影,而这次投影丢掉了一个轴。赤纬就是当同样的天体改从天赤道量起时所剩下的东西 ——印刷星历表里的第二张表,也是任何相位格中都没有的坐标。
这个轴上住着两样东西,而它们在黄道星盘里都看不见:
- 平行相位与反平行相位。 两颗赤纬相同的天体构成一个平行相位,其作用如同合相。距赤道同样 远却位于相反一侧则是反平行相位,作用如同对分相。两者都可能出现在黄经上毫无相位关系的天体 之间。
- 出界(out of bounds)。 超出太阳自身最大赤纬的天体。月亮在大停变期前后每月有几天如此;水星、 金星、火星和冥王星则时有时无。这是一个真实且被广泛讨论的状态,而几乎没有面向消费者的软件会报告 它。
所需模块
两个端点都需要 declination:calc 模块。所有套餐均已包含,且不单独出售。
某一时刻的赤纬
curl -X POST "https://api.astroapi.cloud/api/calc/declination" \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"dateTime": "1990-06-15T14:30",
"location": {
"latitude": 52.37,
"longitude": 4.89,
"timezone": "Europe/Amsterdam"
},
"orb": 1
}'参数
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
dateTime | string | 是 | YYYY-MM-DDTHH:mm,location 处的当地钟表时间 |
location | object | 是 | latitude、longitude 以及 IANA 的 timezone |
points | array | 否 | 要计算的天体点。默认为十大天体、两个交点和两个莉莉丝 |
orb | number | 否 | 平行与反平行相位的容许度,0–3 度。默认为 1 |
moonCenter | string | 否 | topocentric(默认)或 geocentric |
这里的容许度不是那里的容许度
赤纬容许度比黄经容许度窄得多。1 度是惯例,也是默认值;超过 2 度,几乎任何天体都会与某个天体平行。
响应
{
"data": {
"dateTime": "1990-06-15T12:30:00.000Z",
"points": {
"sun": {
"pointId": "sun",
"declination": 23.32,
"declinationDms": [23, 19, 12],
"rightAscension": 84.1,
"latitude": 0,
"speedDeclination": 0.04,
"outOfBounds": false,
"hemisphere": "north"
},
"moon": {
"pointId": "moon",
"declination": -18.44,
"declinationDms": [18, 26, 24],
"rightAscension": 312.7,
"latitude": -4.61,
"speedDeclination": -3.1,
"outOfBounds": false,
"hemisphere": "south"
}
},
"aspects": [
{
"pointA": "venus",
"pointB": "mars",
"aspect": "parallel",
"orb": 0.31,
"applying": true,
"declinationA": 21.08,
"declinationB": 21.39
}
],
"extremes": {
"northernmost": "sun",
"southernmost": "moon",
"outOfBoundsCount": 0
},
"obliquity": 23.4405
}
}declinationDms 是以 [度, 分, 秒] 表示的绝对值;方向在 hemisphere 中,也体现在 declination 的正负号上。speedDeclination 是每日度数,为负表示向南——它告诉你一个平行相位是入相 还是出相,正是黄经相位中 applying 所回答的同一个问题。
出界的界线
obliquity 是所请求日期黄道的真黄赤交角——太阳自身的最大赤纬,也就是 outOfBounds 所依据的界线。 返回它是为了让客户端可以直接画出那条带,而不必自行编造一个界限。
惯用数值是 23°26'。但真实值会移动:章动可使其偏移多达 9 角秒,这足以让一个临界情形倒向任一边。与 返回的 obliquity 比较,和与写死的 23.4367 比较,对恰好落在线上的天体会给出不同答案。
太阳永远不会出界
按定义如此——条件是「超出太阳」。恰好落在界线上的天体并未出界;它必须越过界线。
一段时期内的赤纬
另一半,也是它自成一个端点而非本命盘上一个字段的原因:赤纬图是一条时间序列,而天体越过出界界线的 日期,才是占星师真正会记下来的东西。
curl -X POST "https://api.astroapi.cloud/api/calc/declination/series" \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2025-01-01",
"endDate": "2025-12-31",
"stepDays": 2,
"points": ["sun", "moon", "mercury", "venus", "mars", "pluto"]
}'参数
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
startDate | string | 是 | YYYY-MM-DD 或 ISO 8601 |
endDate | string | 是 | YYYY-MM-DD 或 ISO 8601 |
stepDays | number | 否 | 序列点之间的天数,0.25–30。默认为 1 |
points | array | 否 | 要绘制的天体点。默认值同上 |
响应
{
"data": {
"startDate": "2025-01-01T00:00:00.000Z",
"endDate": "2025-12-31T23:59:00.000Z",
"stepDays": 2,
"points": ["sun", "moon", "mercury", "venus", "mars", "pluto"],
"series": {
"moon": [
["2025-01-01T00:00:00.000Z", -14.02],
["2025-01-03T00:00:00.000Z", 8.71]
]
},
"crossings": [
{
"pointId": "moon",
"date": "2025-03-06T07:41:12.000Z",
"direction": "out",
"declination": 23.4392
},
{
"pointId": "moon",
"date": "2025-03-10T02:18:55.000Z",
"direction": "in",
"declination": 23.4392
}
]
}
}越界点并不按 stepDays 采样
月亮越出界线的一次外出只持续几天。以周为步长绘制的序列会直接跨过去——所以越界点是在比序列返回时更 细的网格上搜索的,随后每一个都会对照星历表精确到秒。
实际后果是:较大的 stepDays 让你失去曲线的形状,却绝不会失去一个越界日期。只需索取图表所需的分辨 率,不必更多。
序列上限
一条序列上限为 400 个点。一年按日步长是 365 个点;十年按日步长是 3653 个点,会返回 400,并 建议加大步长:
{
"error": "That range at a 1-day step is 3654 points; the limit is 400. Widen stepDays or shorten the range."
}无论如何这都是一次请求。用 400 次单独调用来拼出同一张表,会从你的月度配额中消耗 400 次请求;序列 端点在一次遍历中算完,只计为一次。
本命盘中的赤纬
自 API 版本 2026-09-10 起,本命盘响应中的每个天体点也会带有 declination 和 outOfBounds,因此星盘可以不必再调用一次就标出出界的天体:
curl -X POST "https://api.astroapi.cloud/api/calc/natal" \
-H "X-Api-Key: your-api-key" \
-H "X-Api-Version: 2026-09-10" \
-H "Content-Type: application/json" \
-d '{ "dateTime": "1990-06-15T14:30", "location": { "latitude": 52.37, "longitude": 4.89, "timezone": "Europe/Amsterdam" } }'使用较早版本的调用方仍会得到它一直以来收到的响应形状。关于如何固定版本,参见 API 版本控制。
本命盘响应只带这两个字段。平行相位、反平行相位、赤经、赤纬速度以及序列,全都在上面的端点上。
这不是什么
这里没有 3D 视图,而且是有意为之。赤纬的正确图像是一条相对于轴的线;天球会让它更好看,却不会让它更 清楚。