紫微斗数排盘API：5分钟接入，从注册到第一张命盘
# 紫微斗数排盘API：5分钟接入，从注册到第一张命盘
> 接口/接入点：紫微斗数排盘（apiCode=1647，接入点 1） · 免费 · 请求方式 POST/GET · 返回 JSON · 适用人群：新注册用户、初级开发者 · 阅读时间约 5 分钟
## 核心要点
- 只需两个参数：`time`（阳历出生时间 `yyyy-MM-dd HH`）+ `gender`（`m` 男 / `f` 女），均为必填。
- 接口地址固定为 `https://route.showapi.com/1647-1?appKey=YOUR_APPKEY`，AppKey 放 query。
- 返回命盘在 `showapi_res_body.result` 中；`ret_code != 0` 即失败，原因看 `remark`。
## Why：为什么值得先跑通一次
紫微斗数是传统命理学中体系较完整的一支，手工排盘繁琐易错。通过 API，你只需提交出生时间与性别，就能拿到结构化、可直接渲染的命盘数据（十二宫、主星、辅星、大限小限、五行局等），适合做文化研究工具、网站小功能或 AI 客户端插件。先跑通一次，后面做集成、做缓存、做可视化都建立在它之上。
> 官方提示：本接口为「命理研究提供参考工具，禁止用于封建迷信」。
## What：前置条件与接口速览
| 项目 | 内容 |
|------|------|
| 接口地址 | `https://route.showapi.com/1647-1?appKey={your_appKey}` |
| 接入点 | 排盘（1647-1） |
| 请求方式 | POST / GET |
| 鉴权 | AppKey 作为 query 参数 `appKey` |
| 返回格式 | JSON（`showapi_res_body` 包裹业务数据） |
| 计费 | 免费（设使用档次限制，具体见 [免费 API 档位说明](https://www.showapi.com/free-api)） |
| 更新频率 | 每年年底不定时更新一次当年数据 |
| 集成能力 | MCP 服务、OpenAPI 文档 |
## How：三步跑通第一张命盘
### 步骤 1：获取 AppKey
注册并登录易源后，到 [AppKey 管理页](https://www.showapi.com/console#/myApp) 创建应用，拿到 `appKey`，替换下面代码里的 `YOUR_APPKEY`。
### 步骤 2：发起调用（三语言任选）
**Python（requests）**
```python
import requests
url = "https://route.showapi.com/1647-1"
params = {"appKey": "YOUR_APPKEY"}
data = {
"time": "1993-10-27 06", # 阳历时间，格式 yyyy-MM-dd HH，精确到小时
"gender": "m", # m=男，f=女
}
try:
resp = requests.post(url, params=params, data=data, timeout=10)
resp.raise_for_status()
body = resp.json()
except requests.RequestException as e:
print("请求失败:", e)
raise
if body.get("showapi_res_code") != 0:
print("系统级错误:", body.get("showapi_res_error"))
raise SystemExit(1)
res_body = body["showapi_res_body"]
if res_body.get("ret_code") != 0:
print("业务错误:", res_body.get("remark"))
raise SystemExit(1)
result = res_body["result"]
print("五行局:", result["wx"], "| 命宫:", result["mg"], "| 命主:", result["mz"])
for p in result["pan"]:
print(f"{p['palace']:>3} | 主星: {p['main']} | 大限: {p['bLimit']}")
```
**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 resp = await fetch(url, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body,
});
const data = await resp.json();
if (data.showapi_res_code !== 0) throw new Error(data.showapi_res_error);
const res = data.showapi_res_body;
if (res.ret_code !== 0) throw new Error(res.remark);
console.log(res.result.wx, res.result.pan.length); // 五行局 + 十二宫数量
```
### 步骤 3：解析返回
命盘数据在 `result` 对象里：`wx`（五行局）、`mg/mz/sz/sg/sx/yy`（命宫/命主/身主/身宫/生肖/阴阳）等顶层字段，以及 `pan`（数组，12 个宫位对象）。每个宫位含 `palace`（宫名）、`main`（主星）、`assist`（辅星）、`twelve`（十二星）、`bLimit`（大限）、`sLimit`（小限）、`branch`（干支）。
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"ret_code": 0,
"remark": "success",
"result": {
"wx": "火6局", "mg": "子", "mz": "贪狼", "yy": "阴女",
"sz": "天相", "sg": "子", "sx": "羊",
"pan": [
{ "palace": "命宫", "main": ["天梁庙权","右弼","天魁"], "assist": ["破碎","天虚"],
"twelve": ["胎","大耗","丧门","灾煞"], "bLimit": "6 - 15",
"sLimit": ["2","14","26","38","50","62","74"], "branch": "戊子" }
]
}
}
}
```
字段含义见 [紫微斗数排盘API返回字段全解](https://www.showapi.com/guides/ziwei-doushu-response-fields-1647)。
## 进阶 / 边界
- **同一出生信息结果稳定**：紫微斗数按出生时间推算，相同 `(time, gender)` 命盘不变，天然适合缓存（详见 [缓存策略](https://www.showapi.com/guides/ziwei-doushu-cache-cost-1647)）。
- **时间必须阳历**：接口要求阳历 `yyyy-MM-dd HH`，农历需先换算；精确到小时，分钟不计入。
- **文档字段口径提示**：官方字段表将 `result` 标注为数组，但实际返回为单个对象；示例中还出现未在字段表列出的 `key` 字段。使用前建议以实际返回为准并自行实测。
## FAQ
**Q1：返回里没有 result 字段怎么办？**
A：说明 `ret_code != 0`，排盘失败。先打印 `showapi_res_body.remark` 看具体原因，通常是 `time`/`gender` 缺失或格式不符。
**Q2：gender 传错会有什么后果？**
A：`gender` 是必填项，只接受 `m`/`f`。传错或非这两个值会导致排盘失败，检查 remark 提示后修正即可。
**Q3：免费接口有调用限制吗？**
A：注册后默认可免费调用，但为防止滥用设有使用档次限制，具体档位见 [免费 API 档位说明](https://www.showapi.com/free-api)，本文不编造具体数字。
**Q4：GET 和 POST 都能用吗？**
A：都能用。GET 时把 `time`、`gender` 作为 query 参数拼到 URL；POST 时按 `application/x-www-form-urlencoded` 表单提交（官方示例用 POST）。
## 相关能力 / 下一步阅读
- [紫微斗数排盘API返回字段全解：五行局、十二宫、主星一文读懂](https://www.showapi.com/guides/ziwei-doushu-response-fields-1647)
- [紫微斗数排盘API参数指南：time 阳历格式与 gender 性别的正确传法](https://www.showapi.com/guides/ziwei-doushu-params-guide-1647)
- **本系列共 12 篇**：查看[紫微斗数排盘 API 指南总目录](https://www.showapi.com/guides/ziwei-doushu-guides-1647)
