生肖运势查询：5 分钟接入，从注册到第一条运势结果
# 生肖运势查询：5 分钟接入，从注册到第一条运势结果
> 元信息：生肖运势查询（接入点 1） · 免费 · POST / GET · JSON · 新注册用户、初级开发者 · 阅读约 5 分钟
## 核心要点
- 接口**免费**，注册易源账号、拿到 AppKey 即可调用，仅设使用档位限制防滥用。
- 唯一必填参数是 `sx`（12 生肖拼音码，如 `hou`=猴），其余参数均可省略。
- 返回包在 `showapi_res_body` 中，业务成功看 `ret_code == 0`；本文给出可直接运行的 Python / cURL / Node.js 三语言示例。
## Why：这跟我有什么关系
如果你在做日历、星座/生肖、情感或生活类小程序/网站，生肖运势是高频的"轻量内容"素材——用户每天想看自己今天事业/财运/桃花怎么样、幸运色是什么。这个接口**免费、单接入点、返回结构清晰**，非常适合作为你产品的"每日打卡"模块，几行代码就能接上，不需要自己维护运势数据。
## What：前置条件与接口速览
| 项 | 说明 |
|----|------|
| 接口地址 | `https://route.showapi.com/2219-1?appKey={your_appKey}` |
| 接入点 | 生肖运势查询（接入点 1） |
| 请求方式 | POST / GET |
| 鉴权 | query 参数 `appKey`（从控制台获取） |
| 必填参数 | `sx`：12 生肖拼音码（shu/niu/hu/tu/long/she/ma/yang/hou/ji/gou/zhu） |
| 选填参数 | `needTomorrow`（1=返回明日）、`needMonth`（1=返回本月），默认不需要 |
| 返回格式 | JSON，业务数据在 `showapi_res_body` |
| 计费 | 免费（设使用档位限制，以官方档位说明为准） |
| 更新频率 | 每两小时更新 12 生肖最新运势 |
| 超时建议 | 官方读写超时均为 15s，客户端建议设 15s |
前置条件：① 已注册易源账号；② 在控制台创建应用拿到 `appKey`；③ 开发环境能发 HTTPS 请求。
## How：第一次调用
下面以查询「猴（`sx=hou`）」的今日运势为例。把 `YOUR_APPKEY` 换成你自己的 AppKey 即可运行。
### Python（requests）
```python
import requests
url = "https://route.showapi.com/2219-1"
params = {"appKey": "YOUR_APPKEY", "sx": "hou"} # sx 必填：hou=猴
try:
r = requests.get(url, params=params, timeout=15)
r.raise_for_status()
data = r.json()
except requests.RequestException as e:
print("请求失败:", e)
raise
body = data.get("showapi_res_body", {})
if body.get("ret_code") != 0:
print("业务失败:", body.get("remark"))
else:
day = body.get("day", {})
print("生肖:", body.get("shenxiao"))
print("今日事业:", day.get("career_txt"))
print("今日财运:", day.get("money_txt"))
print("财运指数:", day.get("money_star"), "/5")
print("幸运颜色:", day.get("lucky_color"), "幸运方位:", day.get("lucky_direction"))
```
### cURL
```bash
curl -X POST "https://route.showapi.com/2219-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
--data-urlencode "sx=hou"
```
### Node.js（fetch）
```javascript
const url = "https://route.showapi.com/2219-1?appKey=YOUR_APPKEY&sx=hou";
try {
const resp = await fetch(url, { method: "GET", signal: AbortSignal.timeout(15000) });
const data = await resp.json();
const body = data.showapi_res_body || {};
if (body.ret_code !== 0) {
console.log("业务失败:", body.remark);
} else {
const day = body.day || {};
console.log("生肖:", body.shenxiao);
console.log("今日事业:", day.career_txt);
console.log("财运指数:", day.money_star, "/5");
console.log("幸运颜色:", day.lucky_color, "幸运方位:", day.lucky_direction);
}
} catch (e) {
console.log("请求失败:", e.message);
}
```
## 返回示例与解析
```json
{
"showapi_res_error": "",
"showapi_res_code": 0,
"showapi_res_id": "cacbb4186b3a4d93ab9dbda5e3298673",
"showapi_res_body": {
"ret_code": 0,
"remark": "查询成功！",
"shenxiao": "申猴",
"day": {
"love_txt": "在感情方面没有太多的变化，",
"time": "20200204",
"money_txt": "今天的财运不错",
"lucky_noble": "属鼠的人",
"career_txt": "在工作中今天很有耐心",
"lucky_jewelry": "蓝宝石",
"money_star": 3,
"lucky_color": "浅蓝色",
"lucky_num": "1",
"career_star": 4,
"love_star": 2,
"lucky_direction": "正东方向"
},
"sx": "hou"
}
}
```
字段要点：`ret_code` 为 0 表示成功；`shenxiao` 返回「申猴」这种"天干+生肖"全称；`day` 是今日运势对象，含事业/财运/爱情文案、`*_star` 指数（最高 5）与幸运色/方位/数字/饰物/贵人。`sx` 在 `day` 内也会回传拼音码。
## 进阶 / 边界
- **返回体积**：默认只返 `day`（今日）。需要明日加 `needTomorrow=1`，需要本月加 `needMonth=1`，两者可同时开。详见《[生肖运势查询：如何同时拿到今日 / 明日 / 本月运势](https://www.showapi.com/guides/shengxiao-fortune-daily-monthly-2219)》。
- **免费额度**：接口免费但设使用档位限制，正式上线建议做缓存（数据每 2 小时才更新），见《[生肖运势查询：每 2 小时更新，如何设计缓存避免重复调用](https://www.showapi.com/guides/shengxiao-fortune-cache-2219)》。
- **AppKey 安全**：前端直接暴露 AppKey 有泄露风险，生产环境应由后端代理转发，见《[生肖运势查询：集成到网站 / 小程序 / 公众号的实战方案](https://www.showapi.com/guides/shengxiao-fortune-app-integration-2219)》。
## FAQ
**Q1：调用返回 ret_code 非 0 怎么办？**
A：ret_code 非 0 表示业务失败，先看 `remark` 提示。最常见原因是 `sx` 缺传或传了不在 12 个拼音码范围内的值，请核对参数。
**Q2：接口真的免费吗？有次数限制吗？**
A：文档标注为免费服务，注册后默认可调用，为防止滥用设有使用档次限制。具体档位以官方档位说明（https://www.showapi.com/free-api）为准，本文不列举具体数字。
**Q3：GET 和 POST 用哪个？**
A：两种都支持。简单查询用 GET（参数放 URL）即可；若团队规范统一或参数更长，可用 POST（content-type 为 application/x-www-form-urlencoded）。
**Q4：每天数据多久更新一次？**
A：官方说明每两小时更新 12 生肖最新运势，因此同一生肖短时间内结果一致，适合做缓存。
**Q5：返回的运势能直接展示给用户吗？**
A：可以。运势内容属娱乐/参考性质，建议在产品中以"仅供参考"措辞呈现，避免过度承诺。
## 相关能力 / 下一步阅读
- [生肖运势查询：返回字段全解（day / month / tomorrow 三大对象差异与指数说明）](https://www.showapi.com/guides/shengxiao-fortune-response-fields-2219)
- [生肖运势查询：sx 参数（12 生肖拼音编码）正确用法与对照表](https://www.showapi.com/guides/shengxiao-fortune-sx-param-2219)
- [生肖运势查询：用 HTML + JS 做一个生肖运势卡片 Demo（含指数与开运信息展示）](https://www.showapi.com/guides/shengxiao-fortune-web-demo-2219)
- **本系列共 9 篇**：查看[生肖运势查询指南总目录](https://www.showapi.com/guides/shengxiao-fortune-guides-2219)
