星座运势查询：5 分钟接入指南（从注册到第一条每日运势）
星座运势查询API快速接入Python示例免费接口 # 星座运势查询：5 分钟接入指南（从注册到第一条每日运势）
> 接入点 872-1 · 免费 · POST/GET · JSON · 适用：新注册用户、初级开发者 · 阅读时间：约 5 分钟
## TL;DR
- 星座运势查询是 ShowAPI 接口 872 的接入点 1，传入十二星座英文码 `star` 即可返回当日运势。
- 三步跑通：注册拿 AppKey → 拼接请求 → 解析 `showapi_res_body.day`。
- 数据每天 1/7/17 点更新；免费调用但设档位限制，正式上线前建议做缓存。
## Why：为什么值得接
做星座社区、社交 App、会员增值或「每日签」功能时，你不需要自己维护运势内容。调用一个接口就能拿到结构化的综合/爱情/财富/工作指数、贵人星座、幸运数字、吉时方位和运势简评，直接渲染到前端。因为数据每日更新且免费，非常适合作为用户留存钩子。
## What：前置条件与接口速览
| 项 | 值 |
|----|----|
| 接口地址 | `https://route.showapi.com/872-1?appKey={your_appKey}` |
| 接入点 | 872-1（星座运势查询） |
| 请求方式 | POST / GET |
| 返回格式 | JSON（业务数据在 `showapi_res_body` 内） |
| 鉴权 | AppKey（URL 参数或表单参数 `appKey`） |
| 计费 | 免费（设档位限制，见免费档位说明） |
| 更新频率 | 每天 1 点、7 点、17 点 |
| 集成能力 | MCP、OpenAPI 3.0、多语言示例 |
请求参数（全部可选）：`star`（星座英文码）、`date`（MMdd，无 star 时自动转星座）、`needTomorrow/needWeek/needMonth/needYear`（0/1 开关）。
## How：第一次调用
### 步骤 1：获取 AppKey
登录后在 [AppKey 管理](https://www.showapi.com/console#/myApp) 复制你的 AppKey，替换下方 `YOUR_APPKEY`。
### 步骤 2：发起请求（以狮子座 `shizi` 为例）
Python（requests）：
```python
import requests
url = "https://route.showapi.com/872-1"
params = {
"appKey": "YOUR_APPKEY",
"star": "shizi", # 狮子座；不传则可用 date 自动识别
"needTomorrow": 0,
"needWeek": 0,
"needMonth": 0,
"needYear": 0,
}
r = requests.get(url, params=params, timeout=10)
data = r.json()
if data.get("showapi_res_code") != 0:
raise RuntimeError(f"系统错误: {data.get('showapi_res_error')} (code={data.get('showapi_res_code')})")
body = data["showapi_res_body"]
if str(body.get("ret_code")) != "0":
raise RuntimeError(f"业务错误: ret_code={body.get('ret_code')}")
print(body["day"]) # 本日运势列表
```
cURL：
```bash
curl -G "https://route.showapi.com/872-1" \
--data-urlencode "appKey=YOUR_APPKEY" \
--data-urlencode "star=shizi"
```
Node.js（fetch）：
```js
const url = new URL("https://route.showapi.com/872-1");
url.searchParams.set("appKey", "YOUR_APPKEY");
url.searchParams.set("star", "shizi");
const res = await fetch(url, { signal: AbortSignal.timeout(10000) });
const data = await res.json();
if (String(data.showapi_res_body?.ret_code) !== "0") throw new Error("业务失败");
console.log(data.showapi_res_body.day);
```
### 步骤 3：解析返回
业务数据在 `showapi_res_body.day`（数组）。`day[0]` 含 `summary_star`（综合指数）、`love_star`、`money_star`、`work_star`、`grxz`（贵人星座）、`lucky_num`、`lucky_color`、`lucky_time`、`lucky_direction`、`general_txt` 等。详见[返回字段全解](https://www.showapi.com/guides/horoscope-response-fields-872)。
## 返回示例（结构示意）
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"day": [
{
"summary_star": "4",
"love_star": 3,
"money_star": 4,
"work_star": 3,
"grxz": "处女座",
"lucky_num": "7",
"lucky_time": "14:00-16:00",
"lucky_direction": "正东",
"day_notice": "今日宜主动沟通",
"general_txt": "（运势简评示例）",
"love_txt": "（爱情运势示例）",
"work_txt": "（工作运势示例）",
"money_txt": "（财富运势示例）",
"time": "2026-08-27",
"lucky_color": "湖蓝"
}
],
"star": "shizi",
"ret_code": "0"
}
}
```
> 字段名与官方文档一致，具体文案为示意；指数字段类型以实际返回为准（文档内部对 `summary_star` 标注不一致，见[指数怎么读](https://www.showapi.com/guides/horoscope-index-meaning-872)）。
## 进阶 / 边界
- **免费但有限流**：虽然免费，平台设档位限制且数据每日仅更新 3 次，强烈建议做缓存，见[缓存策略](https://www.showapi.com/guides/horoscope-cache-872)。
- **自动识别**：不传 `star` 时可传 `date=MMdd` 让其按生日推断星座（[详解](https://www.showapi.com/guides/horoscope-by-date-872)）。
- **多周期**：用 `needTomorrow/needWeek/needMonth/needYear` 一次取多周期（[详解](https://www.showapi.com/guides/horoscope-multi-period-872)）。
## FAQ
**Q：星座英文码有哪些？**
A：共 12 个——baiyang(白羊)、jinniu(金牛)、shuangzi(双子)、juxie(巨蟹)、shizi(狮子)、chunv(处女)、tiancheng(天秤)、tianxie(天蝎)、sheshou(射手)、mojie(摩羯)、shuiping(水瓶)、shuangyu(双鱼)。
**Q：调用返回 appKey err 怎么办？**
A：`showapi_res_code` 为 -1004 表示 AppKey 校验失败，检查是否复制完整、是否在正确账号下、接口是否对当前账号开放。详见[错误排查](https://www.showapi.com/guides/horoscope-error-handling-872)。
**Q：免费接口有调用次数限制吗？**
A：文档仅说明「为防止滥用设有使用档次限制」，未给具体数字，以[免费档位说明](https://www.showapi.com/island/free-api)为准，请勿自行估算。
**Q：返回里的 day 是数组还是对象？**
A：文档定义为 `Object[]`（数组），通常取 `day[0]`。实际多周期对象（tomorrow/week/month/year）是否仅在对应开关开启时返回，文档未明确，已标注为需实测项。
## 下一步阅读
- [星座运势查询返回字段全解](https://www.showapi.com/guides/horoscope-response-fields-872)
- [星座运势查询：用生日自动识别星座](https://www.showapi.com/guides/horoscope-by-date-872)
- [免费接口也有限流：星座运势查询缓存策略](https://www.showapi.com/guides/horoscope-cache-872)
- **本系列共 13 篇**：查看[星座运势 API 开发指南总目录](https://www.showapi.com/guides/horoscope-guides-872)
