Xích vĩ
Một lá số chiêm tinh là phép chiếu lên hoàng đạo, và phép chiếu ấy vứt bỏ một trục. Xích vĩ là những gì còn lại khi cùng những thiên thể đó được đo từ xích đạo trời — bảng thứ hai trong một cuốn lịch thiên văn in, và là toạ độ không có mặt trong bất kỳ lưới góc chiếu nào.
Trên trục ấy có hai thứ, và không thứ nào hiện ra trong một lá số hoàng đạo:
- Song song và phản song song. Hai thiên thể cùng xích vĩ tạo thành một song song (parallel), hoạt động như một giao hội. Cùng khoảng cách tới xích đạo nhưng ở hai phía đối nhau là một phản song song (contraparallel), hoạt động như một đối lập. Cả hai đều có thể xảy ra giữa những thiên thể không tạo góc chiếu nào theo hoàng kinh.
- Ngoài giới hạn (out of bounds). Một thiên thể vượt quá xích vĩ cực đại của chính Mặt Trời. Mặt Trăng ở trạng thái này vài ngày mỗi tháng quanh kỳ dừng lớn; Thuỷ tinh, Kim tinh, Hoả tinh và Diêm Vương tinh thì theo từng đợt. Đây là một trạng thái có thật và được bàn luận nhiều, vậy mà gần như không phần mềm phổ thông nào báo cáo nó.
Module Bắt buộc
Cả hai điểm cuối đều cần module declination:calc. Module này có trong mọi gói và không bán riêng.
Xích vĩ tại một thời điểm
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
}'Tham số
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
dateTime | string | Có | YYYY-MM-DDTHH:mm, giờ đồng hồ địa phương tại location |
location | object | Có | latitude, longitude và một timezone IANA |
points | array | Không | Các điểm cần tính. Mặc định là mười thiên thể, cả hai giao điểm và cả hai Lilith |
orb | number | Không | Sai số cho song song và phản song song, từ 0 đến 3 độ. Mặc định 1 |
moonCenter | string | Không | topocentric (mặc định) hoặc geocentric |
Sai số ở đây không phải sai số ở kia
Sai số xích vĩ hẹp hơn nhiều so với sai số hoàng kinh. Một độ là quy ước và cũng là giá trị mặc định; vượt quá hai độ thì gần như mọi thứ đều song song với một thứ gì đó.
Phản hồi
{
"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 là độ lớn dưới dạng [độ, phút, giây]; phía nằm ở hemisphere và ở dấu của declination. speedDeclination tính bằng độ mỗi ngày, giá trị âm nghĩa là đi về phía nam — đó là thứ cho biết một song song đang tiến tới hay đang rời xa, đúng câu hỏi mà applying trả lời cho một góc chiếu theo hoàng kinh.
Giới hạn của "ngoài giới hạn"
obliquity là độ nghiêng thực của hoàng đạo vào ngày được yêu cầu — xích vĩ cực đại của chính Mặt Trời, và do đó là giới hạn mà outOfBounds được đánh giá dựa vào. Nó được trả về để một client có thể vẽ dải mà không phải tự bịa ra một giới hạn riêng.
Con số quy ước là 23°26'. Con số thực thì dịch chuyển: chương động làm nó lệch tới chín giây cung, và chừng đó đủ để quyết định một trường hợp sát ranh giới theo hướng này hay hướng kia. So sánh với obliquity được trả về và so sánh với một giá trị cứng 23.4367 sẽ cho câu trả lời khác nhau đối với một thiên thể nằm đúng trên đường ranh.
Mặt Trời không bao giờ ngoài giới hạn
Theo định nghĩa — điều kiện là "vượt quá Mặt Trời". Một thiên thể nằm đúng trên giới hạn thì không phải ngoài giới hạn; nó phải vượt qua giới hạn.
Xích vĩ theo một khoảng thời gian
Nửa còn lại, và cũng là lý do đây là một điểm cuối riêng chứ không phải một trường trong lá số gốc: biểu đồ xích vĩ là một chuỗi theo thời gian, và những ngày mà một thiên thể vượt qua giới hạn ngoài giới hạn mới là thứ nhà chiêm tinh thực sự ghi lại.
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"]
}'Tham số
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
startDate | string | Có | YYYY-MM-DD hoặc ISO 8601 |
endDate | string | Có | YYYY-MM-DD hoặc ISO 8601 |
stepDays | number | Không | Số ngày giữa các điểm của chuỗi, từ 0,25 đến 30. Mặc định 1 |
points | array | Không | Các điểm cần vẽ. Giá trị mặc định như trên |
Phản hồi
{
"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
}
]
}
}Các lần vượt ranh không được lấy mẫu theo stepDays
Một lần Mặt Trăng ra ngoài giới hạn kéo dài vài ngày. Một chuỗi vẽ theo bước tuần sẽ bước thẳng qua nó — vì vậy các lần vượt ranh được tìm trên một lưới mịn hơn lưới mà chuỗi được trả về, rồi từng lần được tinh chỉnh lại theo lịch thiên văn tới từng giây.
Hệ quả thực tiễn: một stepDays rộng khiến bạn mất hình dạng của đường cong, nhưng không bao giờ mất một ngày vượt ranh. Hãy yêu cầu đúng độ phân giải mà biểu đồ cần, không hơn.
Giới hạn của chuỗi
Một chuỗi bị giới hạn ở 400 điểm. Một năm với bước ngày là 365 điểm; một thập kỷ với bước ngày là 3653 điểm và sẽ trả về 400 kèm lời khuyên nới rộng bước:
{
"error": "That range at a 1-day step is 3654 points; the limit is 400. Widen stepDays or shorten the range."
}Dù thế nào thì đây cũng chỉ là một yêu cầu. Dựng cùng bảng đó từ 400 lệnh gọi riêng lẻ sẽ tốn 400 yêu cầu trong hạn mức hằng tháng của bạn; điểm cuối chuỗi tính chúng trong một lượt duy nhất và chỉ tính là một.
Xích vĩ trong lá số gốc
Từ phiên bản API 2026-09-10 trở đi, mọi điểm trong phản hồi lá số gốc cũng mang declination và outOfBounds, nhờ đó một bánh xe có thể đánh dấu một thiên thể ngoài giới hạn mà không cần lệnh gọi thứ hai:
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" } }'Một bên gọi ở phiên bản cũ hơn vẫn giữ nguyên hình dạng phản hồi mà họ luôn nhận được. Xem Phiên bản API để biết cách ghim một phiên bản.
Phản hồi lá số gốc chỉ mang hai trường đó. Song song, phản song song, xích kinh, tốc độ xích vĩ và chuỗi đều nằm ở các điểm cuối bên trên.
Đây không phải là gì
Ở đây không có chế độ xem 3D, và đó là chủ ý. Hình ảnh đúng của xích vĩ là một đường so với một trục; một thiên cầu làm nó đẹp hơn chứ không làm nó rõ hơn.