# 5 分钟接入黄历运势：从注册到第一条黄历数据
> 接口 黄历运势（apiCode=856） · 免费服务 · 请求方式 POST/GET · 返回格式 JSON · 适用人群：新注册用户、初级开发者 · 阅读时间约 5 分钟
## TL;DR
- 黄历运势是 **免费** 接口，黄历 / 吉神凶煞 / 吉时 三个接入点共用一个 AppKey。
- 唯一必填业务参数是 `ymd`（公历日期，格式 `yyyyMMdd`，如 `20260211`）。
- 业务数据包裹在 `showapi_res_body` 中，`ret_code = 0` 表示查询成功。
## Why：为什么值得花 5 分钟接一下
无论你做 **传统文化 App、婚庆/择日工具、日历提醒、生肖运势卡片**，还是想在网站/小程序里给日期加一行「宜忌」，黄历运势都能用一次调用把「农历、干支、宜、忌、冲煞、值神、吉凶神、十二时辰吉凶」等数据直接拿到，省去自己维护万年历与神煞规则的麻烦。它是 ShowAPI 官方自营的免费服务，无需商务洽谈即可开始。
## What：接口速览
| 项目 | 内容 |
|------|------|
| 接口名 | 黄历运势 |
| apiCode | 856 |
| 服务商 | 昆明秀派科技有限公司（易源官方自营） |
| 所属分类 | 生活服务 |
| 计费 | 免费服务 |
| 接入点 | 黄历（856-2）、吉神凶煞（856-4）、吉时（856-3） |
| 请求方式 | POST / GET |
| 返回格式 | JSON |
| 鉴权 | AppKey（query 参数 `appKey`） |
| 必填参数 | `ymd`（公历日期，格式 `yyyyMMdd`） |
| 更新频率 | 每年 1 月 1 日—1 月 3 日早上 9 点更新一次 |
| 查询范围 | 1901-01-01 起至当前年份 |
| 集成能力 | MCP 服务、OpenAPI 3.0 文档（接口级，覆盖全部接入点） |
> 接口详情：[黄历运势（apiCode=856）](https://www.showapi.com/apiGateway/view/856)
## How：三步跑通第一条数据
### 步骤 1：注册并获取 AppKey
1. 打开 [ShowAPI 控制台 · 我的应用](https://www.showapi.com/console#/myApp)，注册/登录后创建一个应用，拿到 `appKey`。
2. 黄历运势为免费服务，无需单独购买套餐即可调用（调用仍占用账户的按次调用次数，详见 [缓存策略](https://www.showapi.com/guides/huangli-cache-cost-856)）。
### 步骤 2：第一次调用（以「黄历」接入点 856-2 为例）
**Python（requests）**
```python
import requests
url = "https://route.showapi.com/856-2"
params = {"appKey": "YOUR_APPKEY", "ymd": "20260211"} # ymd 为公历日期 yyyyMMdd
try:
resp = requests.get(url, params=params, timeout=10)
data = resp.json()
except Exception as e:
print("请求异常：", e)
raise
body = data.get("showapi_res_body", {})
if body.get("ret_code") == 0:
print("公历：", body.get("gongli"))
print("农历：", body.get("nongli"))
print("宜：", body.get("yi"))
print("忌：", body.get("ji"))
print("冲煞：", body.get("chongsha"))
else:
print("查询失败：", body.get("msg"))
```
**cURL**
```bash
curl "https://route.showapi.com/856-2?appKey=YOUR_APPKEY&ymd=20260211"
```
**Node.js（fetch）**
```js
const url = "https://route.showapi.com/856-2?appKey=YOUR_APPKEY&ymd=20260211";
const resp = await fetch(url, { method: "GET" });
const data = await resp.json();
const body = data.showapi_res_body || {};
if (body.ret_code === 0) {
console.log("公历：", body.gongli, "| 农历：", body.nongli);
console.log("宜：", body.yi, "| 忌：", body.ji);
} else {
console.log("查询失败：", body.msg);
}
```
> 把 `YOUR_APPKEY` 替换成你的真实 AppKey 即可运行。吉时接入点用 `856-3`、吉神凶煞用 `856-4`，参数完全一致。
### 步骤 3：解析返回
返回结构一律是「系统级字段 + `showapi_res_body` 业务包」：
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"ret_code": 0,
"gongli": "公元 2025年2月11日 星期二",
"nongli": "二零二五年正月(大)十四",
"yi": "动土 修造 装修 拆卸 出行",
"ji": "祈福 安葬",
"chongsha": "冲鸡煞西 正冲癸酉(1933 1993)",
"msg": "查询成功"
}
}
```
判断成功只看 `showapi_res_body.ret_code == 0`；非 0 时按 `msg` 排查（常见是日期格式/范围问题，见 [错误码排查](https://www.showapi.com/guides/huangli-error-codes-856)）。
## 返回示例（黄历接入点 856-2）
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"ret_code": 0,
"nongli": "二零二五年正月(大)十四",
"zhishen": "玉堂(黄道日)",
"jieqi24": "2月3日立春 2月18日雨水",
"nayin": "[年]壁上土 [月]霹雷火 [日]城墙土",
"tszf": "占门厕外正南",
"shengxiao": "属鼠",
"rulueli": "2460717.5",
"xsyj": "岁刑 伐日 九丑 月刑 天罡 死神 天吏 天贼 致死",
"xingzuo": "摩羯座",
"ganzhi": "庚子年 戊子月 己卯日",
"dizhi": "今日与羊、猪半合，与狗六合，较为吉祥；与鸡相冲，与龙相害，与鼠相刑。",
"pzbj": "己不破券二比并亡 卯不穿井水泉不香",
"zhiri": "平执位(凶)",
"msg": "查询成功",
"gongli": "公元 2025年2月11日 星期二",
"jsyq": "天恩 神在 五合 民日 天德 玉堂 不将",
"ji": "祈福 安葬",
"jieri": "元旦",
"qixiang": "今日二九第2天 进九第11天",
"chongsha": "冲鸡煞西 正冲癸酉(1933 1993)",
"yi": "动土 修造 装修 拆卸 出行",
"wxcy": ""
}
}
```
完整字段说明见 [黄历运势返回字段全解](https://www.showapi.com/guides/huangli-response-fields-856)。
## FAQ
**Q1：黄历运势真的免费吗？会不会有隐藏收费？**
A：是免费服务（官方标注「免费服务」）。调用会占用账户的按次调用次数；`ret_code=0` 时扣除次数，非 0 失败不扣。具体档位以你的账户套餐为准。
**Q2：ymd 支持农历或「今天」这种写法吗？**
A：不支持。`ymd` 只接受公历日期、格式固定为 `yyyyMMdd`（如 `20260211`）。要查「今天」，由你的程序先取当天公历日期再传入。
**Q3：能查未来的日期吗？比如明年？**
A：接口支持 1901-01-01 起至**当前年份**的日期。早于 1901-01-01 或晚于当前年份的日期不在支持范围内，可能返回失败。
**Q4：三个接入点要申请三次吗？**
A：不用。一个 AppKey 即可调用全部接入点，靠接口地址里的 `856-2 / 856-3 / 856-4` 区分。
**Q5：POST 和 GET 有什么区别？**
A：业务结果一致，按你的后端习惯选。示例里用 GET（参数放 URL），生产环境也可用 POST（参数放 body，`content-type: application/x-www-form-urlencoded`）。
## 相关能力 / 下一步阅读
- [黄历运势返回字段全解：黄历/吉神凶煞/吉时字段一文读懂](https://www.showapi.com/guides/huangli-response-fields-856) —— 建立字段认知，避免猜字段。
- [黄历查询接入点详解：宜忌、冲煞、值神怎么用](https://www.showapi.com/guides/huangli-day-almanac-856) —— 深入 856-2 每个字段的业务含义。
- [黄历运势错误码与 ret_code 排查：日期格式/范围边界](https://www.showapi.com/guides/huangli-error-codes-856) —— 调不通时先来这里。
- **本系列共 11 篇**：查看[黄历运势指南总目录](https://www.showapi.com/guides/huangli-guides-856)
