节假日查询返回字段全解：ret_code 与 type(1/2/3) 及三接入点结构一文读懂
# 节假日查询返回字段全解：ret_code 与 type(1/2/3) 及三接入点结构一文读懂
> 接口 894（全部接入点） · 免费 · POST/GET · 返回 JSON · 适用人群：初级/中级开发者 · 阅读时间：约 8 分钟
## TL;DR
- 所有业务数据都在 `showapi_res_body` 里，外层是统一的系统包裹（`showapi_res_code` 等）。
- **ret_code 类型不一致**：894-4 是字符串 `"0"`，894-6 / 894-7 是数字 `0`（894-7 失败为 `-1`）——判断时统一转字符串最稳。
- `type` 只在 894-6 出现：`1`=工作日、`2`=周末、`3`=节假日。
## Why：为什么值得先读这篇
节假日查询有三个接入点，返回结构各不相同。如果照着一个接入点的经验去解析另一个，很容易踩类型坑（字符串 vs 数字）、字段缺失（某接入点没有 `type`）、数组结构不同（`inverse_days` 在两个接入点里长得不一样）。这篇把三张"字段地图"摊开对照，后续写代码直接照表查。
## What：统一返回包裹
无论调哪个接入点，外层都是 ShowAPI 统一包裹：
| 字段 | 类型 | 说明 |
|------|------|------|
| showapi_res_code | Integer | API 返回的状态码 |
| showapi_res_error | String | API 返回的错误信息 |
| showapi_res_id | String | API 请求唯一标识 |
| showapi_fee_num | Integer | 本次调用计费次数（免费接口为 0 或相应值） |
| showapi_res_body | Object | 业务数据均在此对象内 |
**判断成功的标准**：看 `showapi_res_body.ret_code`。⚠️ 各接入点类型不同，下文分述。
## How：三接入点字段对照
### 894-4 假日列表（按年查全年）
| 字段 | 类型 | 说明 |
|------|------|------|
| ret_code | **String** | `"0"` 表示成功 |
| data | Object[] | 整年节假日列表 |
| data[].begin / end | String | 起止日期，如 `20250501` |
| data[].holiday | String | 名称，如「劳动节」 |
| data[].holiday_remark | String | 描述（含调休说明） |
| data[].inverse_days | **String[]** | 调修日列表，如 `["20250427"]`，仅 2021 年后有值 |
### 894-6 节假日查询（按日判定）
| 字段 | 类型 | 说明 |
|------|------|------|
| ret_code | **Number** | `0` 表示成功，其他为失败 |
| day | String | 查询的日期 |
| type | **String** | `1`=工作日、`2`=周末、`3`=节假日 |
| weekDay | Number | 星期几的数字 |
| cn / en | String | 星期几的中文 / 英文名 |
| holiday | String | 节日名称；工作日显示「无」，周末显示「周末」 |
| holiday_remark | String | 节日备注 |
| begin / end | String | 节日或周末起止时间；**工作日时为空串** |
| h | Object[] | 节日简介数组，**仅当 `needDesc=1` 或 `2` 时出现** |
`h[]` 元素：`day`（公历日期）、`genus`（`public`=公众日/国际日、`traditional`=传统节日）、`info`（简介）、`name`（名称）、`lunaDay`（农历日期）、`origin`（起源）。
### 894-7 调休日列表（查补班日）
| 字段 | 类型 | 说明 |
|------|------|------|
| ret_code | **Number** | `0` 成功，`-1` 失败 |
| remark | String | 错误信息（失败时填写） |
| inverse_days | **Object[]** | 当年所有调休日 |
| inverse_days[].name | String | 调休的节日 |
| inverse_days[].begin / end | String | 调休起止日期 |
## 返回示例
**894-4 成功**
```json
{
"showapi_res_body": {
"ret_code": "0",
"data": [{ "holiday": "劳动节", "begin": "20250501", "end": "20250505",
"holiday_remark": "5月1日（周四）至5日（周一）放假调休，共5天。", "inverse_days": ["20250427"] }]
}
}
```
**894-6 成功（含 h，needDesc=1）**
```json
{
"showapi_res_body": {
"ret_code": 0,
"day": "20260101",
"type": "3",
"cn": "星期四",
"holiday": "元旦",
"begin": "20260101",
"end": "20260103",
"h": [{ "day": "20260101", "genus": "public", "name": "元旦", "lunaDay": "", "info": "…", "origin": "…" }]
}
}
```
**894-7 失败**
```json
{
"showapi_res_body": { "ret_code": -1, "remark": "年份参数错误" }
}
```
## 进阶 / 边界
- **健壮的成功判断**：`if str(body["showapi_res_body"]["ret_code"]) == "0"` 可同时兼容字符串与数字，推荐统一这么写。
- **894-7 失败读 remark 而非 showapi_res_error**：业务级错误写在 `remark` 字段。
- **不传 needDesc 就没有 h**：894-6 默认不返回节日简介，需要简介时显式传 `needDesc=1`（全部）或 `2`（仅法定节假日）。
## FAQ
**Q1：ret_code 到底是字符串还是数字？**
A：894-4 是字符串 `"0"`，894-6 / 894-7 是数字 `0`。统一用 `str(...)` 判断最安全。
**Q2：type 字段在所有接入点都有吗？**
A：没有。`type`（1 工作日/2 周末/3 节假日）只在 894-6 出现。894-4 用 `holiday` 字段表达，894-7 用 `inverse_days` 表达调休。
**Q3：两个 inverse_days 一样吗？**
A：不一样。894-4 的 `inverse_days` 是 String[]（如 `["20250427"]`，仅 2021 后）；894-7 的 `inverse_days` 是 Object[]（含 name/begin/end）。
**Q4：怎么判断某天是不是节假日？**
A：用 894-6 传 `day`，看 `type` 是否为 `3`。详见 [节假日查询：某天到底放不放假？](https://www.showapi.com/guides/holiday-query-day-check-894)。
**Q5：h 字段为什么有时返回空？**
A：未传 `needDesc`，或当日无节日。传 `needDesc=1` 即可返回。
## 相关能力 / 下一步阅读
- [节假日查询：5 分钟接入，从注册到拿到全年放假安排](https://www.showapi.com/guides/holiday-query-quickstart-894)
- [节假日查询：某天到底放不放假？894-6 单日判定接入指南](https://www.showapi.com/guides/holiday-query-day-check-894)
- [节假日查询：节日简介与农历日期怎么拿？needDesc 与 h 字段实战](https://www.showapi.com/guides/holiday-query-festival-intro-894)
- **本系列共 12 篇**：查看[节假日查询指南总目录](https://www.showapi.com/guides/holiday-query-guides-894)
