生肖运势查询：sx 参数（12 生肖拼音编码）正确用法与对照表
# 生肖运势查询：sx 参数（12 生肖拼音编码）正确用法与对照表
> 元信息：生肖运势查询（接入点 1） · 免费 · POST / GET · JSON · 初级/中级开发者 · 阅读约 5 分钟
## 核心要点
- `sx` 是**唯一必填参数**，取值为 12 个固定拼音码，不是中文、也不是数字。
- 12 个拼音码与中文生肖一一对应：`shu`=鼠、`niu`=牛、`hu`=虎、`tu`=兔、`long`=龙、`she`=蛇、`ma`=马、`yang`=羊、`hou`=猴、`ji`=鸡、`gou`=狗、`zhu`=猪。
- 传错或缺失会触发 `ret_code` 非 0，以 `remark` 提示为准；建议前端用下拉或映射表把"中文"转成拼音码。
## Why：为什么专门讲一个参数
`sx` 是整个接口唯一不能省略的字段，且它用**拼音码**而非中文。新手常犯两类错：一是直接传中文"猴"或数字"9"，结果返回失败；二是自己猜拼音写错（如把"蛇"写成 `she` 是对的，但容易拼成 `snake`）。本文给出权威对照表与前端映射建议，确保一次传对。
## What：参数定义
| 参数 | 位置 | 必填 | 类型 | 取值 |
|------|------|------|------|------|
| `sx` | query / form | **是** | string | 12 个拼音码之一（见下表） |
| `needTomorrow` | query / form | 否 | string | `1`=返回明日（默认不需要） |
| `needMonth` | query / form | 否 | string | `1`=返回本月（默认不需要） |
### 12 生肖拼音码对照表（官方取值）
| 拼音码（传参值） | 中文生肖 | 拼音码（传参值） | 中文生肖 |
|------------------|----------|------------------|----------|
| `shu` | 鼠 | `yang` | 羊 |
| `niu` | 牛 | `hou` | 猴 |
| `hu` | 虎 | `ji` | 鸡 |
| `tu` | 兔 | `gou` | 狗 |
| `long` | 龙 | `zhu` | 猪 |
| `she` | 蛇 | — | — |
| `ma` | 马 | — | — |
> 提示：`long`（龙）、`she`（蛇）、`hou`（猴）、`ji`（鸡）、`gou`（狗）、`zhu`（猪）均为官方文档列出的真实取值，直接照抄即可。
## How：正确传参与常见错误
### Python：用映射表把中文转拼音码
```python
SX_MAP = {
"鼠": "shu", "牛": "niu", "虎": "hu", "兔": "tu", "龙": "long",
"蛇": "she", "马": "ma", "羊": "yang", "猴": "hou", "鸡": "ji",
"狗": "gou", "猪": "zhu",
}
def query_fortune(cn_name: str):
code = SX_MAP.get(cn_name)
if not code:
raise ValueError(f"未知生肖: {cn_name}")
resp = requests.get(
"https://route.showapi.com/2219-1",
params={"appKey": "YOUR_APPKEY", "sx": code},
timeout=15,
)
body = resp.json().get("showapi_res_body", {})
if body.get("ret_code") != 0:
print("业务失败:", body.get("remark"))
return body
```
### 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 code = "hou"; // 猴
const url = `https://route.showapi.com/2219-1?appKey=YOUR_APPKEY&sx=${code}`;
const data = await (await fetch(url, { signal: AbortSignal.timeout(15000) })).json();
if (data.showapi_res_body.ret_code !== 0) {
console.log("业务失败:", data.showapi_res_body.remark);
}
```
## 返回示例与解析
成功时 `showapi_res_body.sx` 会回传你传入的拼音码，`shenxiao` 给出可读全称：
```json
{
"showapi_res_body": {
"ret_code": 0,
"remark": "查询成功！",
"shenxiao": "申猴",
"sx": "hou",
"day": { "time": "20200204", "career_star": 4, "money_star": 3 }
}
}
```
## 进阶 / 边界
- **不要传中文或数字**：接口只认上表的 12 个拼音码。若产品 UX 用中文选择，务必在前端/后端做一次 `中文 → 拼音码` 映射（如上 `SX_MAP`）。
- **12 生肖不含"猫"等**：仅传统 12 生肖；传入范围外的值会返回 `ret_code` 非 0。
- **大小写**：文档示例均为小写，建议统一小写传参，避免大小写不一致导致匹配失败。
## FAQ
**Q1：能直接传中文"猴"吗？**
A：不能。`sx` 只接受 12 个拼音码（如 `hou`）。中文需先映射成拼音码再传，否则返回失败。
**Q2：传错 sx 会返回什么？**
A：返回 `ret_code` 非 0，并附带 `remark` 提示。文档未枚举具体非 0 错误码，排查以 `remark` 文案为准。
**Q3：为什么返回里既有 sx 又有 shenxiao？**
A：`sx` 是入参拼音码回传（如 hou），`shenxiao` 是"天干+生肖"可读全称（如申猴）。展示给用户用 `shenxiao` 更友好，业务逻辑用 `sx` 即可。
**Q4：龙/蛇这些拼音会不会拼错？**
A：官方取值就是 `long`/`she`/`hou`/`ji`/`gou`/`zhu`，直接照本文对照表复制，不要自创（如 `snake`、`dragon` 都不行）。
**Q5：需要一次性查多个生肖怎么办？**
A：本接入点一次只接收一个 `sx`。要查多个生肖需循环调用（注意免费档位限制，建议加缓存），详见《[生肖运势查询：每 2 小时更新，如何设计缓存避免重复调用](https://www.showapi.com/guides/shengxiao-fortune-cache-2219)》。
## 相关能力 / 下一步阅读
- [生肖运势查询：5 分钟接入，从注册到第一条运势结果](https://www.showapi.com/guides/shengxiao-fortune-quickstart-2219)
- [生肖运势查询：返回字段全解（day / month / tomorrow 三大对象差异与指数说明）](https://www.showapi.com/guides/shengxiao-fortune-response-fields-2219)
- [生肖运势查询：如何同时拿到今日 / 明日 / 本月运势（needTomorrow / needMonth 开关）](https://www.showapi.com/guides/shengxiao-fortune-daily-monthly-2219)
- **本系列共 9 篇**：查看[生肖运势查询指南总目录](https://www.showapi.com/guides/shengxiao-fortune-guides-2219)
