紫微斗数排盘API参数指南：time 阳历格式与 gender 性别的正确传法
# 紫微斗数排盘API参数指南：time 阳历格式与 gender 性别的正确传法
> 接口/接入点：紫微斗数排盘（apiCode=1647，接入点 1） · 免费 · 请求方式 POST/GET · 适用人群：集成开发者 · 阅读时间约 6 分钟
## 核心要点
- 仅两个必填参数：`time`（阳历出生时间）与 `gender`（性别），**缺一不可**。
- `time` 格式严格为 `yyyy-MM-dd HH`（24 小时制，精确到小时），分钟不计入。
- `gender` 仅接受 `m`（男）/ `f`（女），大小写敏感，写错会排盘失败。
## Why：参数为什么值得单独讲
紫微斗数完全由出生时间与性别决定，参数一旦传错，返回要么直接失败、要么命盘错位（比如把男命排成女命）。这一篇把两个参数的格式、边界、常见坑讲透，能省掉你大半调试时间。
## What：参数速览
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `time` | String | 是 | 阳历时间，格式 `yyyy-MM-dd HH`（如 `1993-10-27 06`） |
| `gender` | String | 是 | 求卦者性别：`m`=男，`f`=女 |
| `content-type` | String（Header） | 否 | POST 时建议 `application/x-www-form-urlencoded` |
> 接口地址：`https://route.showapi.com/1647-1?appKey={your_appKey}`；AppKey 走 query 参数。
## How：正确传参的三语言示例
**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，24小时制
"gender": "m", # 男=m，女=f
}
resp = requests.post(url, params=params, data=data, timeout=10).json()
res = resp["showapi_res_body"]
if res.get("ret_code") != 0:
raise SystemExit(f"排盘失败: {res.get('remark')}")
print(res["result"]["wx"])
```
**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();
if (data.showapi_res_body.ret_code !== 0)
throw new Error(data.showapi_res_body.remark);
```
## 返回示例与解析
成功时 `ret_code=0`、`remark="success"`，`result` 含完整命盘。失败时无 `result`，仅 `remark` 描述原因（官方文档未给细分错误码枚举，统一以 `ret_code != 0` + `remark` 判定）。
## 进阶 / 边界
- **必须是阳历**：接口明确要「阳历时间」。如果用户输入的是农历，需先换算成阳历再提交，否则命盘整体错位。
- **小时制与精度**：`HH` 为 24 小时制（如 `06` 表示早上 6 点、`18` 表示晚上 6 点）；只精确到小时，分钟部分即使传入也不影响排盘。
- **时区**：以用户出生地的阳历当地时间为准；跨时区/夏令时等历史细节接口未提供换算能力，需在业务侧自行处理。
- **gender 大小写**：文档示例用小写 `m`/`f`，建议严格小写，避免服务端对大小写敏感导致失败。
## FAQ
**Q1：time 写成 1993-10-27 6（不带前导零）可以吗？**
A：不建议。格式约定为 `yyyy-MM-dd HH`（两位小时），写成 `6` 可能不符合服务端解析规则，优先用 `06` 这类两位补零写法。
**Q2：用户填的是农历怎么办？**
A：接口只接受阳历。需要在调用前用农历转阳历的工具/接口换算，再提交换算后的 `time`，否则命盘错误。
**Q3：能不能只传 time 不传 gender？**
A：不能。`gender` 是必填项，缺省或为空会导致排盘失败，返回 `ret_code != 0`，原因见 `remark`。
**Q4：GET 方式怎么传这两个参数？**
A：直接拼到 URL：`?appKey=YOUR_APPKEY&time=1993-10-27%2006&gender=m`（注意空格编码为 `%20`）。POST 则用表单字段提交。
## 相关能力 / 下一步阅读
- [紫微斗数排盘API：5分钟接入，从注册到第一张命盘](https://www.showapi.com/guides/ziwei-doushu-quickstart-1647)
- [紫微斗数排盘API返回字段全解：五行局、十二宫、主星一文读懂](https://www.showapi.com/guides/ziwei-doushu-response-fields-1647)
- [紫微斗数排盘API如何集成到传统文化网站？从出生表单到命盘可视化](https://www.showapi.com/guides/ziwei-doushu-website-integration-1647)
- **本系列共 12 篇**：查看[紫微斗数排盘 API 指南总目录](https://www.showapi.com/guides/ziwei-doushu-guides-1647)
