星座运势查询不传 needX 开关会返回什么？五个周期实测规则
约 12 分钟 进阶星座运势查询多周期needX开关一次取全
# 星座运势查询不传 needX 开关会返回什么？五个周期实测规则
接入点 872-1 · 免费服务 · POST / GET · 返回 JSON · 适用：需要多周期展示的开发者 · 阅读时间：约 6 分钟 · 最后实测核对：2026-09-18
## 核心要点
- 星座运势查询接口（apiCode=872）的接入点 1 用四个开关控制周期返回：`needTomorrow`、`needWeek`、`needMonth`、`needYear`，`day` 始终返回。
- 开关不传或传 `0` 时，对应周期的键**完全不出现在** `showapi_res_body` 里，不是返回空对象或空数组。
- 一次请求带齐四个开关，就能拿到今日加明日加本周加本月加本年的全部数据，不必调五次。
## 开关的实测行为
2026-09-18 对 `https://route.showapi.com/872-1` 做了两组对照：
只带 `star=shizi`、不带任何 `needX` 时，`showapi_res_body` 的键只有 `day`、`ret_code`、`star`。
带上 `star=shizi` 与 `needWeek=1` 时，键变成 `day`、`ret_code`、`star`、`week`。另外三个周期键依然不出现。
带齐四个开关时，键为 `day`、`tomorrow`、`ret_code`、`week`、`star`、`year`、`month`，共 7 个。
按「开哪个用哪个」编码即可，取值前对每个周期判空，不会拿到 `null` 或空数组这类中间状态。
## 四个开关
| 参数 | 取值 | 作用 |
|---|---|---|
| `needTomorrow` | `1` 为需要，其他不需要 | 返回 `tomorrow` 明日运势 |
| `needWeek` | `1` 为需要，其他不需要 | 返回 `week` 本周运势 |
| `needMonth` | `1` 为需要，其他不需要 | 返回 `month` 本月运势 |
| `needYear` | `1` 为需要，其他不需要 | 返回 `year` 本年运势 |
| `day` 今日 | 无开关 | 始终返回 |
文档口径是「1 为需要，其他不需要」，所以传 `0`、`2`、空串都等同不需要。四个参数都是可选的。
## 一次取齐五个周期
Python（requests）：
```python
import requests
PERIODS = ("day", "tomorrow", "week", "month", "year")
def fetch_periods(star: str, appkey: str) -> dict:
data = requests.get(
"https://route.showapi.com/872-1",
params={
"appKey": appkey,
"star": star,
"needTomorrow": "1",
"needWeek": "1",
"needMonth": "1",
"needYear": "1",
},
timeout=15,
).json()
if data.get("showapi_res_code") != 0:
raise RuntimeError(f"系统错误: {data.get('showapi_res_error')}")
body = data["showapi_res_body"]
if str(body.get("ret_code")) != "0":
raise RuntimeError(f"业务错误: {body.get('remark')}")
# 未打开的周期不会出现对应键，这里统一判空后再用
return {p: body.get(p) for p in PERIODS if body.get(p)}
result = fetch_periods("shizi", "YOUR_APPKEY")
print(sorted(result.keys())) # ['day', 'month', 'tomorrow', 'week', 'year']
print(result["year"]["general_index"]) # 形如 "77分"
```
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");
url.searchParams.set("appKey", "YOUR_APPKEY");
url.searchParams.set("star", "shizi");
["needTomorrow", "needWeek", "needMonth", "needYear"]
.forEach(k => url.searchParams.set(k, "1"));
const data = await (await fetch(url, { signal: AbortSignal.timeout(15000) })).json();
const body = data.showapi_res_body;
if (String(body.ret_code) !== "0") throw new Error(body.remark);
const periods = ["day", "tomorrow", "week", "month", "year"]
.filter(k => body[k]); // 未打开的周期键不存在，filter 后自然过滤掉
console.log(periods);
console.log(body.day.time, body.week.time, body.year.time);
```
## 返回示例（2026-09-18 实测，四开关全开，长文案已截断）
```json
{
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": {
"day": { "summary_star": 4, "lucky_color": "金色", "time": "20260918" },
"tomorrow": { "summary_star": 4, "lucky_color": "亮金色", "time": "20260919" },
"week": { "summary_star": 4, "xrxz": "天蝎座", "time": "20260913-20260920" },
"month": { "summary_star": 4, "yfxz": "射手座", "time": "202609" },
"year": { "general_index": "77分", "oneword": "2026年是狮子座……", "time": "2026" },
"star": "shizi",
"ret_code": 0
}
}
```
五个周期的 `time` 格式各不相同，`week` 是区间、`month` 到月、`year` 到年。落库时分开处理，字段对照见返回字段全解那篇。
## 一次请求还是多次请求
| 调用方式 | 网络请求数 | 返回体大小 | 适用场景 |
|---|---|---|---|
| 带齐四个开关一次取 | 1 | 较大，含五段长文 | 需要同时展示多周期 |
| 只开需要的开关 | 1 | 小 | 页面只展示单一周期 |
| 调五次单周期 | 5 | 小 | 不推荐，调用次数是按次计的 |
接入点的计费按调用次数计，`showapi_fee_num` 实测为 `1`。一次带齐多个周期比多次调用更省额度，代价是返回体更大。
基础版档位每日 100 次、1 QPS，暖色数据更新节奏见缓存策略那篇。
## FAQ
**Q1：没传 `needWeek`，返回里会有 `week` 键吗？**
不会有。2026-09-18 实测只带 `needWeek=1` 时返回的键是 `day`、`week`、`star`、`ret_code`；不带任何开关时键只有 `day`、`star`、`ret_code`。关闭的周期键完全不出现。
**Q2：四个开关可以只开一个吗？**
可以，任意组合。`day` 不受开关控制，始终返回。
**Q3：`needTomorrow=0` 和完全不传这个参数有区别吗？**
没有区别。文档口径是「1 为需要，其他不需要」，`0` 与不传都是不返回。
**Q4：`year` 返回什么？和其他周期一样吗？**
不一样。`year` 只有 `general_index`、`love_index`、`money_index`、`work_index` 四个 100 分制指数，加 `oneword` 和几段长文，没有 5 分制的小维度。
**Q5：一次带齐开关会不会更贵？**
不会。计费按调用次数计，一次请求带几个周期都是计一次，返回体更大而已。
## 下一步阅读
- [星座运势查询返回字段全解：五个周期的字段对照](https://www.showapi.com/guides/horoscope-response-fields-872)
- [星座运势查询的指数怎么读：5 分制与 100 分制](https://www.showapi.com/guides/horoscope-index-meaning-872)
- [星座运势查询的缓存怎么设](https://www.showapi.com/guides/horoscope-cache-872)
- [星座运势查询：用 Python / cURL / Node.js 跑通第一次调用](https://www.showapi.com/guides/horoscope-quickstart-872)
- **本系列共 13 篇**：查看[星座运势 API 指南总目录](https://www.showapi.com/guides/horoscope-guides-872)
