星座运势查询返回字段全解：五个周期的字段对照与实测类型
约 16 分钟 进阶星座运势查询返回字段五周期字段全解
# 星座运势查询返回字段全解：五个周期的字段对照与实测类型
接入点 872-1 · 免费服务 · POST / GET · 返回 JSON · 适用：已接入开发者、需要统一渲染模板的工程师 · 阅读时间：约 7 分钟 · 最后实测核对：2026-09-18
## 核心要点
- `showapi_res_body` 里最多同时存在五个周期对象：`day`、`tomorrow`、`week`、`month`、`year`，打开哪个 `needX` 开关就出现哪个。
- 日、明日、周、月四个周期的指数是 5 分制，字段类型实测都是数字；`year` 换成 100 分制，四个 `*_index` 实测是带「分」字的字符串。
- 五个周期的字段并不一致：`week` 有小人星座与本周提醒，`month` 有缘份星座与本月优势弱势，`year` 只有指数加上四段长文。
## 为什么要把字段拉平看一遍
做统一渲染模板时最容易出现的情况是：今日卡片能跑通，切到本周就缺字段，切到本年又被 100 分制的数字撑爆。五个周期对象的字段集合互有增删，先拉一张对照表，后面写模板和落库都省事。
这篇把 2026-09-18 实测到的字段全集、字段类型和空值情况整理成速查表，作为本系列其他文章的字段基准。
## 接口速览
| 项 | 值 |
|---|---|
| 接口地址 | `https://route.showapi.com/872-1?appKey={your_appKey}` |
| 业务根字段 | `day` / `tomorrow` / `week` / `month` / `year` / `star` / `ret_code` |
| 取周期的方式 | 传 `needTomorrow=1`、`needWeek=1`、`needMonth=1`、`needYear=1` |
| 超时 | 读 15 秒 / 连接 15 秒 |
## 实测字段数一览
在 `star=shizi` 且四个开关全部打开的情况下，2026-09-18 实测各周期返回的字段个数：
| 周期 | 对象还是数组 | 字段数 | 指数字段 | 指数类型 |
|---|---|---|---|---|
| `day` | 对象 | 15 | `summary_star`、`love_star`、`money_star`、`work_star` | 数字 |
| `tomorrow` | 对象 | 15 | 同上 | 数字 |
| `week` | 对象 | 17 | 同上 | 数字 |
| `month` | 对象 | 18 | 同上 | 数字 |
| `year` | 对象 | 11 | `general_index`、`love_index`、`money_index`、`work_index` | 字符串带「分」 |
五个周期在接口文档里都标为 `Object[]`，实测返回的是单个对象。
## 逐周期字段说明
### day（今日）与 tomorrow（明日）
两个周期的字段集合完全相同，共 15 个：
`summary_star`（综合指数）、`love_star`（爱情）、`money_star`（财富）、`work_star`（工作）、`grxz`（贵人星座）、`lucky_num`（幸运数字）、`lucky_time`（吉时）、`lucky_direction`（吉利方位）、`lucky_color`（吉色）、`day_notice`（今日提醒）、`general_txt`（简评）、`love_txt`、`work_txt`、`money_txt`、`time`。
### week（本周）
在 `day` 的字段基础上减掉 `lucky_time` 和 `lucky_direction`，加上 `lucky_day`（幸运日期）、`xrxz`（小人星座）、`week_notice`（本周提醒）、`health_txt`（健康运势），共 17 个。
接口文档的 `week` 字段表列了 `lucky_direction`、没有列 `day_notice`；实测 `week` 不含 `lucky_direction`，但保留了 `day_notice`。
### month（本月）
在 `day` 的字段基础上减掉 `lucky_time`，加上 `yfxz`（缘份星座）、`xrxz`（小人星座）、`month_advantage`（本月优势）、`month_weakness`（本月弱势），共 18 个。
接口文档的 `month` 字段表没有列 `lucky_num`、`lucky_color`、`day_notice`，2026-09-18 实测这三个字段都有返回。
### year（本年）
字段最少，共 11 个：`general_index`、`love_index`、`money_index`、`work_index` 四个 100 分制指数，加 `oneword`（一句话简评）、`general_txt`（运势概述）、`love_txt`、`work_txt`、`money_txt`、`health_txt`、`time`。
`year` 没有 5 分制的小维度，做 UI 时不要照搬日维度的模板。
## 返回示例（2026-09-18 真实返回，长文案已截断）
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"day": {
"summary_star": 4, "love_star": 3, "money_star": 4, "work_star": 5,
"grxz": "狮子座", "lucky_num": "54", "lucky_time": "06:00-08:00",
"lucky_direction": "东南方", "lucky_color": "金色",
"day_notice": "保持耐心，稳步前行。", "time": "20260918"
},
"week": {
"summary_star": 4, "love_star": 4, "money_star": 3, "work_star": 5,
"grxz": "狮子座", "xrxz": "天蝎座", "lucky_num": "81",
"lucky_day": "星期三", "lucky_color": "橙色",
"week_notice": "专注细节，把握财运，稳步前行。",
"time": "20260913-20260920"
},
"month": {
"summary_star": 4, "love_star": 4, "money_star": 4, "work_star": 3,
"grxz": "狮子座", "xrxz": "金牛座", "yfxz": "射手座",
"lucky_num": "17", "lucky_color": "橙色", "lucky_direction": "正南方",
"time": "202609"
},
"year": {
"general_index": "77分", "love_index": "77分",
"money_index": "75分", "work_index": "79分",
"time": "2026"
},
"star": "shizi",
"ret_code": 0
}
}
```
`time` 字段的格式随周期变化，落库时别统一按日期解析：
| 周期 | 实测 `time` 值 | 格式 |
|---|---|---|
| `day` | `20260918` | `yyyyMMdd` |
| `tomorrow` | `20260919` | `yyyyMMdd` |
| `week` | `20260913-20260920` | 起止区间 |
| `month` | `202609` | `yyyyMM` |
| `year` | `2026` | `yyyy` |
## 取数与判空的写法
Python：
```python
import requests
PERIODS = ["day", "tomorrow", "week", "month", "year"]
def fetch_all(star: str, appkey: str) -> dict:
params = {
"appKey": appkey,
"star": star,
"needTomorrow": "1", "needWeek": "1", "needMonth": "1", "needYear": "1",
}
data = requests.get("https://route.showapi.com/872-1", params=params, timeout=15).json()
if data.get("showapi_res_code") != 0:
raise RuntimeError(data.get("showapi_res_error"))
body = data["showapi_res_body"]
if str(body.get("ret_code")) != "0":
raise RuntimeError(f"业务错误 ret_code={body.get('ret_code')}")
# 每个周期都判空：未打开的开关不会返回对应键
return {p: body.get(p) for p in PERIODS if body.get(p)}
print(list(fetch_all("shizi", "YOUR_APPKEY").keys()))
```
cURL：
```bash
curl -G "https://route.showapi.com/872-1" \
--data-urlencode "appKey=YOUR_APPKEY" \
--data-urlencode "star=shizi" \
--data-urlencode "needTomorrow=1" \
--data-urlencode "needWeek=1" \
--data-urlencode "needMonth=1" \
--data-urlencode "needYear=1" \
--max-time 15
```
Node.js（fetch）：
```javascript
const url = new URL("https://route.showapi.com/872-1");
["appKey=YOUR_APPKEY", "star=shizi", "needTomorrow=1",
"needWeek=1", "needMonth=1", "needYear=1"]
.forEach(p => {
const [k, v] = p.split("=");
url.searchParams.set(k, v);
});
const data = await (await fetch(url, { signal: AbortSignal.timeout(15000) })).json();
if (String(data.showapi_res_body?.ret_code) !== "0") throw new Error("业务失败");
const { day, tomorrow, week, month, year } = data.showapi_res_body;
// 未打开的周期不会出现，解构后是 undefined，渲染前判空
const cards = { day, tomorrow, week, month, year };
console.log(Object.keys(cards).filter(k => cards[k]));
```
## 类型处理
日、明日、周、月四个周期的指数字段实测都是数字（如 `4`、`5`），转成星级直接可用。`year` 的四个指数是字符串且带「分」字（如 `"77分"`），要先用 `parseInt` 或 `Number()` 去掉单位再算长度。
字段的口径区别与归一化写法见指数怎么读那篇。
## FAQ
**Q1：没打开 `needWeek`，返回里还有 `week` 键吗？**
没有。2026-09-18 实测只带 `needWeek=1` 时，`showapi_res_body` 的键只有 `day`、`week`、`star`、`ret_code`，其余三个周期键不出现。按「开哪个用哪个」编码，取值前判空。
**Q2：`day` 到底是不是数组？**
实测是对象。接口文档把五个周期标为 `Object[]`，2026-09-18 的返回是 `"day": { ... }`。写 `body.day.summary_star`，不要写 `body.day[0]`。
**Q3：`year` 的 100 分和 `day` 的 5 分能放同一根进度条吗？**
不能，量纲不同。`day` 的 `summary_star` 满分 5，`year` 的 `general_index` 满分 100，各自归一化后再渲染。
**Q4：`lucky_color` 每个周期都有吗？**
`day`、`tomorrow`、`week`、`month` 实测都有，`year` 没有。接口文档的 `month` 字段表没列 `lucky_color`，实测有返回。
**Q5：周运的 `time` 是日期还是区间？**
是区间，形如 `20260913-20260920`。落库时建议拆成 `start_date` / `end_date` 两个字段，不要塞进 `date` 类型。
## 下一步阅读
- [星座运势查询：一次取齐五个周期的 needX 开关规则](https://www.showapi.com/guides/horoscope-multi-period-872)
- [星座运势查询的指数怎么读：5 分制与 100 分制](https://www.showapi.com/guides/horoscope-index-meaning-872)
- [星座运势查询：用 Python / cURL / Node.js 跑通第一次调用](https://www.showapi.com/guides/horoscope-quickstart-872)
- [星座运势查询的两层状态码排查](https://www.showapi.com/guides/horoscope-error-handling-872)
- **本系列共 13 篇**：查看[星座运势 API 指南总目录](https://www.showapi.com/guides/horoscope-guides-872)
