星座运势查询：一次取齐今日/明日/本周/本月/年度运势（needX 开关用法）
# 星座运势查询：一次取齐今日/明日/本周/本月/年度运势（needX 开关用法）
> 接入点 872-1 · 免费 · POST/GET · JSON · 适用：需多周期展示的开发者 · 阅读时间：约 6 分钟
## TL;DR
- 接入点 1 用四个 0/1 开关控制返回哪些周期：`needTomorrow`、`needWeek`、`needMonth`、`needYear`（今日 `day` 默认返回）。
- 一次请求可同时拿到今日 + 明日 + 本周 + 本月 + 本年，减少调用次数、规避档位限制。
- 各周期对象是否仅在对应开关为 1 时返回，**文档未明确**，建议按「开哪个用哪个」编码并判空。
## Why：为什么用多周期开关
星座社区/日历类功能常需要在同一页面展示「今日签 + 本周趋势 + 本月优势 + 年度总览」。与其调用五次，不如一次请求带齐四个开关，既省调用额度，又保证数据同源、时间一致。
## What：四个开关
| 参数 | 取值 | 作用 |
|------|------|------|
| `needTomorrow` | 0/1 | 是否返回 `tomorrow[]`（明日） |
| `needWeek` | 0/1 | 是否返回 `week[]`（本周） |
| `needMonth` | 0/1 | 是否返回 `month[]`（本月） |
| `needYear` | 0/1 | 是否返回 `year[]`（本年） |
| `day`（今日） | — | 默认返回，无需开关 |
> 四个参数均为可选，默认 0（不返回对应周期）。
## How：一次取齐多周期
Python（requests）：
```python
import requests
url = "https://route.showapi.com/872-1"
params = {
"appKey": "YOUR_APPKEY",
"star": "shizi",
"needTomorrow": 1,
"needWeek": 1,
"needMonth": 1,
"needYear": 1,
}
r = requests.get(url, params=params, timeout=10)
body = r.json()["showapi_res_body"]
print("今日:", body.get("day"))
print("明日:", body.get("tomorrow"))
print("本周:", body.get("week"))
print("本月:", body.get("month"))
print("本年:", body.get("year"))
```
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"
```
Node.js（fetch）：
```js
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 => url.searchParams.append(...p.split("=")));
const body = (await (await fetch(url, { signal: AbortSignal.timeout(10000) })).json()).showapi_res_body;
console.log(body.day, body.year);
```
## 返回示例（结构示意）
```json
{
"showapi_res_body": {
"day": [{ "summary_star": "4", "lucky_color": "湖蓝" }],
"tomorrow": [{ "summary_star": 4 }],
"week": [{ "summary_star": 4, "xrxz": "双子座" }],
"month": [{ "summary_star": 4, "yfxz": "双鱼座", "month_advantage": "（优势示例）" }],
"year": [{ "general_index": "78", "oneword": "稳中向好" }],
"star": "shizi", "ret_code": "0"
}
}
```
## 进阶 / 边界
- **判空兜底**：由于文档未明确「开关关闭时该周期对象是否仍返回（为空数组/缺省）」，代码务必对每个周期 `get()` 后判空再渲染，避免前端报错。
- **指数量纲不同**：日/周/月为 5 分制，年为 100 分制，见[指数怎么读](https://www.showapi.com/guides/horoscope-index-meaning-872)。
- **一次请求 vs 多次**：带齐开关通常比多次单周期更省额度，但返回体更大；结合[缓存策略](https://www.showapi.com/guides/horoscope-cache-872)效果最佳。
## FAQ
**Q：不传 needWeek 会返回 week 吗？**
A：按文档默认值为 0（不返回）。但文档未明确关闭时对象是否仍存在（空），请判空处理（已标注需实测）。
**Q：四个开关能只开一个吗？**
A：可以，任意组合。今日 `day` 不受开关控制，始终参与返回。
**Q：年维度返回的是什么？**
A：`year[]` 含 `general_index/love_index/money_index/work_index`（最高 100 分）与 `oneword` 等年度概述，量纲与日维度不同。
## 下一步阅读
- [星座运势查询返回字段全解](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)
- **本系列共 13 篇**：查看[星座运势 API 开发指南总目录](https://www.showapi.com/guides/horoscope-guides-872)
