星座运势查询：用 Python / cURL / Node.js 跑通第一次调用
约 13 分钟 入门星座运势查询API快速接入Python示例免费接口
# 星座运势查询：用 Python / cURL / Node.js 跑通第一次调用
接入点 872-1 · 免费服务 · POST / GET · 返回 JSON · 适用：新注册用户、初级开发者 · 阅读时间：约 6 分钟 · 最后实测核对：2026-09-18
## 核心要点
- 星座运势查询接口（apiCode=872）的接入点 1 传一个 `star` 就返回当日运势，`day` 内含 4 个指数、贵人星座、幸运数字、吉色、吉时和四段运势文案。
- 成功要同时满足两层：系统级 `showapi_res_code` 为 `0`，业务级 `showapi_res_body.ret_code` 为 `0`（实测是数字，不是字符串）。
- 五个周期默认只返回 `day`；`tomorrow` / `week` / `month` / `year` 要带上对应的 `needX=1` 才会出现在返回里。
## 为什么值得接
做一个星座社区、社交 App 的「每日签」，或者给会员出一份运势卡片，你不需要自己维护十二星座的文案库。一次请求就能拿到结构化的指数与文案，直接渲染到页面上。
星座运势接口（apiCode=872）是免费的官方自营服务，注册后默认可免费调用。平台为防止滥用设有使用档次限制，具体档位在免费档位说明页，基础版每日 100 次调用、1 QPS 并发。
接口每天 1 点、7 点、17 点更新三次数据（接口文档页「更新频率」字段原文），配合缓存可以覆盖绝大多数请求。
## 接口速览
| 项 | 值 |
|---|---|
| 接口地址 | `https://route.showapi.com/872-1?appKey={your_appKey}` |
| 接入点 | 872-1 星座运势查询 |
| 请求方式 | POST / GET（表单 `application/x-www-form-urlencoded`） |
| 返回格式 | JSON |
| 鉴权 | AppKey |
| 计费 | 免费服务，与同接口其他接入点统一计费 |
| 更新频率 | 每天 1 点、7 点、17 点更新 |
| 超时 | 读 15 秒 / 连接 15 秒（取自 OpenAPI 文档的 `x-read-timeout`、`x-connect-timeout`） |
| 集成能力 | MCP 服务、OpenAPI 3.0 文档 |
请求参数共 6 个，全部可选：`star`、`date`、`needTomorrow`、`needWeek`、`needMonth`、`needYear`。
## 第一次调用
### 步骤 1：拿到 AppKey
登录 ShowAPI 后，在 AppKey 管理里复制你的 AppKey，替换下面代码里的 `YOUR_APPKEY`。
### 步骤 2：发请求
Python（requests）：
```python
import requests
url = "https://route.showapi.com/872-1"
params = {
"appKey": "YOUR_APPKEY",
"star": "shizi", # 狮子座；也可以改用 date="0819" 按生日识别
"needWeek": "1", # 需要本周运势就带上，默认不返回
}
try:
r = requests.get(url, params=params, timeout=15) # 超时对齐文档的 15 秒
r.raise_for_status()
data = r.json()
except requests.RequestException as e:
raise RuntimeError(f"请求失败: {e}")
# 第一层：系统级状态码
if data.get("showapi_res_code") != 0:
raise RuntimeError(f"系统错误 {data.get('showapi_res_code')}: {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')} remark={body.get('remark')}")
day = body["day"] # 实测为对象，不是数组
print(day["summary_star"], day["grxz"], day["lucky_color"])
print(day["general_txt"])
```
cURL：
```bash
curl -G "https://route.showapi.com/872-1" \
--data-urlencode "appKey=YOUR_APPKEY" \
--data-urlencode "star=shizi" \
--data-urlencode "needWeek=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");
url.searchParams.set("needWeek", "1");
try {
const res = await fetch(url, { signal: AbortSignal.timeout(15000) });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
if (data.showapi_res_code !== 0) {
throw new Error(`系统错误: ${data.showapi_res_error}`);
}
const body = data.showapi_res_body;
if (String(body.ret_code) !== "0") {
throw new Error(`业务错误: ${body.remark}`);
}
console.log(body.day.summary_star, body.day.lucky_color);
} catch (e) {
console.error("运势暂不可用:", e.message); // 走兜底文案，不要白屏
}
```
### 步骤 3：读返回
业务数据全在 `showapi_res_body` 内。`star` 回显你查询的星座英文码，`ret_code` 是业务结果，其余键就是各周期对象。
`day` 的字段可以直接映射到一张运势卡片：`summary_star` 做综合星级，`general_txt` 做正文，`lucky_color` 上色，`lucky_num` 做幸运数字，`grxz` 做贵人星座。字段的完整含义见返回字段全解。
## 返回示例（2026-09-18 真实返回，长文案已截断）
```json
{
"showapi_res_error": "",
"showapi_res_id": "6aace609fb638cba8bfa0852",
"showapi_res_code": 0,
"showapi_fee_num": 1,
"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": "保持耐心，稳步前行。",
"general_txt": "今日整体运势呈现上升态势，你的自信与热情感染了周围的人。",
"time": "20260918"
},
"star": "shizi",
"ret_code": 0
}
}
```
三个和文档不完全一致的地方，按实测处理：
| 项 | 接口文档 | 2026-09-18 实测 |
|---|---|---|
| `day` 等五周期 | `Object[]` | 单个对象 |
| `ret_code` | 参数表标 String | 数字 `0` |
| `time` | 未给示例 | 日/明日为 `yyyyMMdd`，周为 `yyyyMMdd-yyyyMMdd`，月为 `yyyyMM`，年为 `yyyy` |
代码里统一用 `str(body.get("ret_code")) != "0"` 判断业务结果，两种类型都能兼容。
## 参数说明
`star` 与 `date` 二选一，至少给一个。`star` 取值是十二星座英文码：`baiyang`、`jinniu`、`shuangzi`、`juxie`、`shizi`、`chunv`、`tiancheng`、`tianxie`、`sheshou`、`mojie`、`shuiping`、`shuangyu`。
`date` 用 `MMdd` 四位数字，接口按这个日期反推星座。两者同时传时以 `star` 为准。
四个 `needX` 开关取值 `1` 表示需要，其他值都不需要。实测只带 `needWeek=1` 时，返回的键只有 `day`、`week`、`star`、`ret_code`，另外三个周期的键不出现。
## FAQ
**Q1：`ret_code` 是字符串还是数字？**
实测返回的是数字 `0`。接口文档的参数表把它标为 String，返回示例里写的是 `0`。判断时用 `str(body.get("ret_code")) != "0"`，两种类型都能接住。
**Q2：什么参数都不传会怎样？**
实测 `showapi_res_code` 仍是 `0`，业务层返回 `{"remark": "星座和月份不能同时为空", "ret_code": -1}`。`star` 与 `date` 至少传一个。
**Q3：`star` 传了接口不认识的取值会怎样？**
实测 `star=xxx` 返回 `ret_code: -1`、`remark: 输入星座不正确`，系统级 `showapi_res_code` 依然是 `0`。判定失败要看第二层。
**Q4：`day` 该按数组还是对象取？**
按对象取，写 `body.day.summary_star`。接口文档把五个周期都标为 `Object[]`，2026-09-18 实测返回的是单个对象。
**Q5：免费接口有调用次数上限吗？**
有档位限制。接口页只说明「为防止滥用设有使用档次限制」，具体数字以免费档位说明页为准：基础版 L0 为每日 100 次、1 QPS。
## 下一步阅读
- [星座运势查询返回字段全解：五个周期怎么取](https://www.showapi.com/guides/horoscope-response-fields-872)
- [星座运势查询的缓存怎么设](https://www.showapi.com/guides/horoscope-cache-872)
- [星座运势查询的 date 参数：按生日识别星座](https://www.showapi.com/guides/horoscope-by-date-872)
- [星座配对：四个必填参数算出配对指数](https://www.showapi.com/guides/constellation-match-quickstart-872)
- **本系列共 13 篇**：查看[星座运势 API 指南总目录](https://www.showapi.com/guides/horoscope-guides-872)
