紫微斗数排盘API返回字段全解：五行局、十二宫、主星一文读懂
# 紫微斗数排盘API返回字段全解：五行局、十二宫、主星一文读懂
> 接口/接入点：紫微斗数排盘（apiCode=1647，接入点 1） · 免费 · 返回 JSON · 适用人群：集成开发者、命理研究者 · 阅读时间约 8 分钟
## 核心要点
- 业务数据全部在 `showapi_res_body` 内；`ret_code=0` 表示成功，`result` 存在即排盘成功。
- `result` 顶层放「全局信息」：五行局 `wx`、命宫 `mg`、命主 `mz`、身主 `sz`、身宫 `sg`、生肖 `sx`、阴阳 `yy`。
- 十二宫在 `result.pan`（数组，12 个元素），每宫含宫名 `palace`、主星 `main`、辅星 `assist`、十二星 `twelve`、大限 `bLimit`、小限 `sLimit`、干支 `branch`。
## Why：为什么先读懂返回结构
做可视化、做缓存、做字段映射，第一步都是把返回结构吃透。紫微斗数返回嵌套不深但字段多，本文把每个字段的含义、类型、示例一次性列清，省去你反复翻文档。后续「十二宫详解」「大限小限解读」「五行局命主解读」三篇都是本文的细化。
## What：返回结构速览
| 层级 | 字段 | 类型 | 说明 |
|------|------|------|------|
| 系统级 | `showapi_res_code` | Number | 0 成功 |
| 系统级 | `showapi_res_body` | Object | 业务数据容器 |
| 业务级 | `ret_code` | Number | 0 成功，其余失败 |
| 业务级 | `remark` | String | 错误信息（成功为 success） |
| 业务级 | `result` | Object | 排盘结果（失败无此字段） |
| result | `wx` | String | 五行局，如「火6局」 |
| result | `mg` | String | 命宫宫位，如「子」 |
| result | `mz` | String | 命主，如「贪狼」 |
| result | `yy` | String | 阴阳，如「阴男」「阳女」 |
| result | `sz` | String | 身主，如「天相」 |
| result | `sg` | String | 身宫，如「子」 |
| result | `sx` | String | 生肖，如「羊」 |
| result | `pan` | Array | 十二宫详情（12 个元素） |
`pan` 每个元素的字段：
| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `palace` | String | 宫名 | 命宫 / 兄弟 / 夫妻 / 子女 / 财帛 / 疾厄 / 迁移 / 仆役 / 事业 / 田宅 / 福德 / 父母 |
| `main` | Array[String] | 主星 | ["天梁庙权","右弼","天魁"] |
| `assist` | Array[String] | 辅星 | ["破碎","天虚"] |
| `twelve` | Array[String] | 十二星（含长生十二神、博士十二神、岁前十二神等） | ["胎","大耗","丧门","灾煞"] |
| `bLimit` | String | 大限（十年一运区间） | "6 - 15" |
| `sLimit` | Array[String] | 小限（每年一运，7 个年龄段） | ["2","14","26","38","50","62","74"] |
| `branch` | String | 干支 | 戊子 |
> 文档字段表未列入、但返回示例中出现的 `key` 字段（如 `"key":"20151210230"`），官方未说明含义，使用前建议以实际返回为准自行实测，本文不臆测其用途。
## How：解析返回并落表
**Python：把十二宫整理成表格**
```python
import requests
url = "https://route.showapi.com/1647-1"
params = {"appKey": "YOUR_APPKEY"}
data = {"time": "1993-10-27 06", "gender": "m"}
resp = requests.post(url, params=params, data=data, timeout=10).json()
res = resp["showapi_res_body"]
if res.get("ret_code") != 0:
raise SystemExit(res.get("remark"))
r = res["result"]
print(f"五行局={r['wx']} 命宫={r['mg']} 命主={r['mz']} 身主={r['sz']} 生肖={r['sx']}")
print(f"{'宫名':<4} | 主星 | 大限 | 干支")
for p in r["pan"]:
print(f"{p['palace']:<4} | {','.join(p['main'])} | {p['bLimit']} | {p['branch']}")
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/1647-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "time=1993-10-27%2006&gender=m"
```
**Node.js（fetch）**
```javascript
const url = "https://route.showapi.com/1647-1?appKey=YOUR_APPKEY";
const body = new URLSearchParams({ time: "1993-10-27 06", gender: "m" });
const data = await (await fetch(url, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body,
})).json();
const r = data.showapi_res_body.result;
console.table(r.pan.map(p => ({
宫名: p.palace, 主星: p.main.join(","), 大限: p.bLimit, 干支: p.branch,
})));
```
## 返回示例与解析
完整返回见 [5分钟接入篇的示例](https://www.showapi.com/guides/ziwei-doushu-quickstart-1647)。要点：
- `pan` 是 **12 个元素**的数组，顺序固定为「命宫→兄弟→夫妻→子女→财帛→疾厄→迁移→仆役→事业→田宅→福德→父母」（与示例一致）。
- `main`/`assist`/`twelve` 都是字符串数组，长度不定（有的宫主星多、有的少）。
- `sLimit` 固定 7 个字符串，对应人生不同阶段的年龄节点。
> 文档将 `result` 标注为 `Object[]`，但官方返回示例中为**单个 Object**。本文以实际返回（单个 Object）描述，属文档口径不一致，使用时以实测返回为准。
## 进阶 / 边界
- **星曜带庙旺利陷后缀**：主星常带「庙/旺/得/平/陷/科/权/禄/忌」等后缀（如「天梁庙权」「太阴平忌」），展示时建议保留原样，这是紫微斗数判断旺衰的关键。
- **数组长度不固定**：不同宫位主星数量不同，前端渲染用循环而非固定下标。
- **仅同步单条**：接口一次返回一张命盘，无批量/订阅能力；多用户需自行循环调用并缓存。
## FAQ
**Q1：ret_code 和 showapi_res_code 有什么区别？**
A：`showapi_res_code` 是系统级状态码（网络/鉴权层），`ret_code` 是业务级（排盘是否成功）。两者都为 0 才算真正成功；任一非 0 都应按对应 remark 处理。
**Q2：为什么我的返回里没有 result？**
A：排盘失败时（ret_code 非 0）不返回 `result`，只返回 `remark` 说明原因。检查 time/gender 是否齐全且格式正确。
**Q3：pan 一定是 12 个吗？**
A：紫微斗数固定十二宫，正常返回为 12 个元素。若数量异常，多为请求参数问题导致排盘失败，先排查参数。
**Q4：key 字段是什么？**
A：返回示例中出现 `key`（如 "20151210230"），但官方字段表未说明其含义。建议按「未公开字段」对待，不要依赖它做业务逻辑，待官方文档补全。
## 相关能力 / 下一步阅读
- [紫微斗数十二宫详解：命宫、财帛、事业等 12 宫字段怎么读](https://www.showapi.com/guides/ziwei-doushu-twelve-palaces-1647)
- [紫微斗数大限与小限解读：bLimit / sLimit 字段推算人生阶段](https://www.showapi.com/guides/ziwei-doushu-limit-interpret-1647)
- [紫微斗数五行局与命主身主解读：wx / mz / sz / sx 字段含义](https://www.showapi.com/guides/ziwei-doushu-wx-mz-sz-1647)
- **本系列共 12 篇**：查看[紫微斗数排盘 API 指南总目录](https://www.showapi.com/guides/ziwei-doushu-guides-1647)
