节假日查询：5 分钟接入，从注册到拿到全年放假安排
# 节假日查询：5 分钟接入，从注册到拿到全年放假安排
> 接口 894（接入点 894-4 假日列表） · 免费 · POST/GET · 返回 JSON · 适用人群：新注册用户、初级开发者 · 阅读时间：约 6 分钟
## TL;DR
- 节假日查询是**免费接口**，注册后拿 AppKey 即可调用，无需付费开通。
- 用 894-4 接入点按年份查询，一条请求就能拿到**全年放假 + 调休上班**清单。
- 三种语言（Python / Node.js / cURL）最小可运行示例，替换 `YOUR_APPKEY` 即可跑。
## Why：这跟我有什么关系
做日历、排班、请假、考勤、证券休市提醒的应用，第一件事就是要知道"哪天放假、哪天要补班"。节假日查询把国务院每年发布的放假安排封装成 API，你不用自己维护一份容易过期的 Excel，直接调接口拿结构化数据。
- **对个人开发者**：免费、无需商务洽谈，注册即用。
- **对产品/团队**：数据是官方自营、每年随国务院文件更新，省去人工维护成本。
## What：接口速览
| 项 | 说明 |
|----|------|
| 接口名 / apiCode | 节假日查询 / 894 |
| 本次用到的接入点 | **894-4 假日列表**（按年查全年节假日） |
| 接口地址 | `https://route.showapi.com/894-4?appKey=YOUR_APPKEY` |
| 请求方式 | POST 或 GET |
| 鉴权 | query 参数 `appKey` |
| 计费 | 免费服务（注册后默认可免费调用，有使用档位限制） |
| 更新频率 | 每年更新数据，一般在国务院发布文件后一周内更新 |
| 集成能力 | MCP、`OpenAPI 3.0`（YAML/JSON）均已提供 |
**请求参数（894-4）**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| year | String | 否 | 需要查询的年份，默认查询当年的节假日列表 |
## How：三步跑通第一次调用
### 步骤 1：获取 AppKey
登录 ShowAPI 控制台 →「我的应用」创建应用，拿到 `appKey`。
### 步骤 2：发请求（以查询 2026 年为例）
**Python（requests）**
```python
import requests
url = "https://route.showapi.com/894-4"
params = {"appKey": "YOUR_APPKEY", "year": "2026"}
try:
r = requests.post(url, params=params, timeout=10)
r.raise_for_status()
body = r.json()
except requests.RequestException as e:
print("请求失败:", e)
raise
# 关键：894-4 的 ret_code 是字符串 "0"，统一转字符串判断，兼容数字型接入点
ret = str(body["showapi_res_body"]["ret_code"])
if ret != "0":
print("接口返回失败:", body.get("showapi_res_error"))
else:
data = body["showapi_res_body"]["data"]
for item in data:
print(item["holiday"], item["begin"], "~", item["end"])
```
**Node.js（fetch）**
```javascript
const url = "https://route.showapi.com/894-4?appKey=YOUR_APPKEY&year=2026";
try {
const res = await fetch(url, { method: "POST", timeout: 10000 });
const body = await res.json();
const ret = String(body.showapi_res_body.ret_code);
if (ret !== "0") {
console.error("接口返回失败:", body.showapi_res_error);
} else {
for (const item of body.showapi_res_body.data) {
console.log(item.holiday, item.begin, "~", item.end);
}
}
} catch (e) {
console.error("请求失败:", e);
}
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/894-4?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "year=2026"
```
### 步骤 3：解析并用起来
返回里的 `data` 是全年节假日数组，每条含 `begin`/`end`（起止日期）、`holiday`（名称）、`holiday_remark`（描述）、`inverse_days`（调修日，仅 2021 年后有值）。把这些画成日历就是你的放假安排。
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"ret_code": "0",
"data": [
{
"holiday": "劳动节",
"holiday_remark": "5月1日（周四）至5日（周一）放假调休，共5天。4月27日（周日）上班。",
"inverse_days": ["20250427"],
"end": "20250505",
"begin": "20250501"
}
]
}
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| showapi_res_body.ret_code | String | "0" 表示成功（注意：这里是字符串） |
| showapi_res_body.data | Object[] | 整年节假日列表 |
| data[].begin / end | String | 节假日起止日期，如 `20250501` |
| data[].holiday | String | 节假日名称，如「劳动节」 |
| data[].holiday_remark | String | 节假日描述（含调休说明） |
| data[].inverse_days | String[] | 调修日列表，仅 2021 年之后的数据有值 |
> 完整字段与三接入点差异见 [节假日查询返回字段全解](https://www.showapi.com/guides/holiday-query-response-codes-894)。
## 进阶 / 边界
- **ret_code 类型坑**：894-4 的 `ret_code` 是字符串 `"0"`，而 894-6/894-7 是数字 `0`。示例代码统一用 `str(...)` 判断，避免踩坑。
- **不传 year**：默认返回当年数据，适合「展示今年日历」场景。
- **免费但有档位限制**：注册后默认可免费调用，但设有使用档次限制防止滥用，具体档位以官方说明为准，不要在代码里硬编码额度。
## FAQ
**Q1：接口要钱吗？**
A：节假日查询是免费服务，注册后默认可免费调用，仅设有使用档位限制（具体以官方档位说明为准）。
**Q2：year 不传会怎样？**
A：默认查询当年的节假日列表。
**Q3：为什么我查不到 2027 年的数据？**
A：次年数据通常在当年 10–11 月随国务院文件更新，未更新前查不到属正常。详见 [节假日查询：为什么只能查 2018 年起？](https://www.showapi.com/guides/holiday-query-data-range-894)。
**Q4：ret_code 返回 "0" 但 data 是空数组？**
A：可能是该年份暂无节假日数据，或参数格式异常。先确认 `showapi_res_error` 是否为空，再核对 year 是否为合法年份字符串。
**Q5：可以用 GET 吗？**
A：可以，接口支持 POST/GET，鉴权都走 `appKey` query 参数。
## 相关能力 / 下一步阅读
- [节假日查询：某天到底放不放假？894-6 单日判定接入指南](https://www.showapi.com/guides/holiday-query-day-check-894)
- [节假日查询：一键生成全年放假日历，894-4 假日列表实战](https://www.showapi.com/guides/holiday-query-year-list-894)
- [节假日查询返回字段全解：ret_code 与 type(1/2/3) 及三接入点结构一文读懂](https://www.showapi.com/guides/holiday-query-response-codes-894)
- **本系列共 12 篇**：查看[节假日查询指南总目录](https://www.showapi.com/guides/holiday-query-guides-894)
