# 黄历运势·吉时查询接入点：如何给用户推荐当日吉时
> 接入点 856-3（吉时） · 免费服务 · 适用人群：开发者、择日/礼仪类应用策划 · 阅读时间约 7 分钟
## TL;DR
- 吉时接入点（856-3）返回 **12 个时辰对象**（子时到亥时），每个含吉凶、吉神、时段、时冲、时柱。
- 每个时辰对象字段一致：`jixiong`(吉凶) / `jishen`(吉神) / `shijian`(时段) / `xiongshen`(凶神) / `shichong`(时冲) / `shizhu`(时柱)。
- 推荐吉时只需遍历 12 对象、筛 `jixiong` 含「吉」的时辰，按 `shijian` 排序展示。
## Why：为什么需要吉时接入点
「今天几点出门/办事最吉利」是高频问题。黄历接入点只给到「日」级别，吉时接入点下沉到「时辰」级别，返回子时到亥时共 12 段的吉凶与神煞。本文讲清如何解析这 12 个对象并做成「当日吉时推荐」。
## What：接入点速览
| 项目 | 内容 |
|------|------|
| 接入点 | 吉时 856-3 |
| 接口地址 | `https://route.showapi.com/856-3?appKey={your_appKey}` |
| 必填参数 | `ymd`（公历日期 `yyyyMMdd`） |
| 返回 | `showapi_res_body` 内 12 个时辰对象 + `msg` + `ut` |
| 查询范围 | 1901-01-01 至当前年份 |
> 字段完整说明见 [黄历运势返回字段全解](https://www.showapi.com/guides/huangli-response-fields-856)。
## How：解析 12 时辰并筛吉时
### 步骤 1：调用
**Python（requests）**
```python
import requests
url = "https://route.showapi.com/856-3"
params = {"appKey": "YOUR_APPKEY", "ymd": "20260211"}
resp = requests.get(url, params=params, timeout=10)
body = resp.json().get("showapi_res_body", {})
if body.get("ret_code") != 0:
print("失败：", body.get("msg"))
else:
shichen = ["zi","chou","yin","mao","chen","si","wu","wei","shen","you","xu","hai"]
lucky = []
for key in shichen:
h = body.get(key, {})
if "吉" in h.get("jixiong", ""):
lucky.append((h.get("shijian"), h.get("jishen")))
print("当日吉时：")
for t, s in lucky:
print(f" {t} {s}")
```
**cURL**
```bash
curl "https://route.showapi.com/856-3?appKey=YOUR_APPKEY&ymd=20260211"
```
**Node.js（fetch）**
```js
const url = "https://route.showapi.com/856-3?appKey=YOUR_APPKEY&ymd=20260211";
const body = (await (await fetch(url)).json()).showapi_res_body || {};
if (body.ret_code !== 0) console.log("失败：", body.msg);
else {
const order = ["zi","chou","yin","mao","chen","si","wu","wei","shen","you","xu","hai"];
const lucky = order.map(k => body[k]).filter(h => h && h.jixiong.includes("吉"));
console.log("当日吉时：", lucky.map(h => `${h.shijian} ${h.jishen}`).join(" / "));
}
```
### 步骤 2：展示
`shijian` 已是标准时间段（如 `23:00:00-0:59:59`），可直接排序展示；`jishen` 给出该时辰吉神名称，适合做标签。
## 返回示例（节选两个时辰）
```json
{
"showapi_res_body": {
"ret_code": 0,
"zi": { "jixiong": "白虎(凶)", "jishen": "文昌贵人", "shijian": "23:00:00-0:59:59", "xiongshen": "白虎", "shichong": "冲马", "shizhu": "戊子" },
"wu": { "jixiong": "青龙(吉)", "jishen": "青龙天乙贵人", "shijian": "11:00:00-12:59:59", "xiongshen": "无", "shichong": "冲鼠", "shizhu": "甲午" },
"ut": "2024-06-04 10:29:05",
"msg": "查询成功"
}
}
```
> 完整返回含 `zi/chou/yin/mao/chen/si/wu/wei/shen/you/xu/hai` 共 12 个时辰对象。
## 进阶 / 边界
- **吉凶口径**：`jixiong` 形如 `司命(吉)`、`白虎(凶)`，括号内标注吉/凶；判定时建议用「是否含『吉』」而非精确匹配，避免个别写法差异。
- **子时跨日**：`zi`(子时) 为 `23:00:00-0:59:59`，跨越午夜，展示时如需归到「当日」需按产品口径处理。
- **`ut` 字段**：示例中出现 `ut`（数据更新时间），非每个时辰都有，解析时按需取用。
## FAQ
**Q1：12 个时辰是固定顺序吗？返回里顺序会变吗？**
A：12 地支时辰（子丑寅卯…亥）是固定顺序；返回对象键顺序可能因序列化变化，建议按固定数组 `zi→hai` 遍历，不依赖返回顺序。
**Q2：怎么只展示「大吉」的时辰？**
A：文档未区分「大吉/中吉」等级，`jixiong` 仅标注吉/凶。如需分级，建议以「吉神名称」或业务规则自行映射，勿臆造等级字段。
**Q3：吉时和黄历的「宜」怎么结合？**
A：吉时管「几点」，黄历管「做什么」。组合方案见 [婚庆搬家择日场景](https://www.showapi.com/guides/huangli-date-selection-856)。
## 相关能力 / 下一步阅读
- [黄历查询接入点详解：宜忌、冲煞、值神怎么用](https://www.showapi.com/guides/huangli-day-almanac-856) —— 日级宜忌。
- [吉神凶煞查询接入点：财神喜神方位与择日应用](https://www.showapi.com/guides/huangli-deities-856) —— 神煞方位。
- [婚庆搬家择日场景：组合黄历+吉神凶煞+吉时做择日推荐](https://www.showapi.com/guides/huangli-date-selection-856) —— 多接入点联动。
- **本系列共 11 篇**：查看[黄历运势指南总目录](https://www.showapi.com/guides/huangli-guides-856)
