日程开发怎么获取当日节假日信息？节假日查询接口使用详解
节假日、调休与工作日判定是日程、排班、投放与日历类应用中反复出现的基础判断。本文以「传入一个日期，即可返回当日是节假日、工作日还是周末，并给出调休补班安排」为核心，讲解一个节假日查询接口的参数设计、调用方式、返回结构、在线调试与工程落地要点，帮助你在业务中快速把「这一天是不是工作日、要不要调休」这类判断从手工维护切换为程序化调用。
一、技术简介
节假日数据有三个绕不开的难点。第一，法定节假日的起止与调休补班由国务院每年发布通知确定，年份之间并不完全一致，靠硬编码的日期表极易过期中断。第二，「周末 + 节假日 + 调休补班」三者叠加后，单日到底是休息还是上班不能靠星期几简单推导，例如某些周六因补班需要上班，有些周末本身又属于假期。第三，除了法定假期，公众日、国际日、传统节日的简介等信息也常被日历与资讯类产品需要。
一个成熟的节假日查询接口把上述判断都封装成了标准 HTTP 调用：业务方传入日期，接口返回该日类型（工作日 / 周末 / 节假日）、星期几的中英文、节日名称、起止区间、调休补班备注，以及可选的节日简介。调用方无需维护本地日期表，也无需自行解析国务院通知，直接拿到结构化结果即可用于展示与逻辑分支。
二、能力概览
该能力围绕「按日期取节假日信息」提供三类互补接口，覆盖从单日到整年的不同粒度需求：
| 接口 | 方法 | 入参 | 返回要点 | 典型用途 |
|---|---|---|---|---|
| 单节假日查询 | GET | day（如 20260501）、needDesc（可选） |
当日类型、节日名、星期几中英文、起止、调休备注、可选节日简介 | 判定某天是否工作日、日历打点 |
| 节假日列表 | GET | year（如 2026） |
全年节假日数组，含起止、名称、调休日列表 | 年度排班、假期规划 |
| 调休日列表 | GET | year（如 2026） |
全年需要上班的调休日列表 | 考勤、补班安排 |
三类接口共用同一套鉴权与返回封装，showapi_res_code 表示网关层调用结果（0 为成功），业务数据放在 showapi_res_body 内，字段含义见「调用示例与返回结构」一节。数据自 2018 年起的历年节假日均可查询，次年数据通常在每年 10 月至 11 月国务院发布通知后更新，更新频率以接口实际为准。
三、适用场景
节假日判定看似简单，实际渗透到很多业务环节，下面列出几类常见落地场景，便于判断是否契合你的需求。
| 场景 | 用到的能力 | 说明 |
|---|---|---|
| 日历与日程应用 | 单节假日查询 | 在日历组件上标注节假日、显示节日名与调休提示 |
| 排班与考勤 | 节假日列表 + 调休日列表 | 生成年度排班、区分正常工作日与补班日 |
| 金融与行情 | 单节假日查询 | 判定是否交易日，决定行情展示与结算逻辑 |
| 电商与投放 | 单节假日查询 | 大促节点、免息分期活动与假期对齐 |
| 资讯与内容 | 单节假日查询（needDesc） |
展示当日国际日 / 传统节日简介 |
四、接入流程
接入一个节假日查询接口，整体分为五步。下图给出从获取凭据到完成首次调用的完整链路。
- 获取调用凭据：在控制台完成开通并获取 AppCode 鉴权信息。AppCode 是接口身份凭据，调用时通过请求头
Authorization: APPCODE <appcode>传入（也可用 AppKey 置于查询参数，二者择一），务必妥善保管、不要硬编码进前端。 - 确定接口与参数：按需求选择单节假日查询、节假日列表或调休日列表，填写对应的
day/year等参数。 - 发起请求：使用 GET 请求拼接参数与鉴权信息，向接口端点发起调用。端点地址在控制台对应接入点中查看。
- 解析返回：先读
showapi_res_code判断网关层是否成功，再从showapi_res_body内读取业务字段。 - 做容错与落地：对参数、空返回、超时做前置校验与重试降级，将结果用于展示或业务判断。
五、调用示例与返回结构
5.1 单节假日查询（本文重点）
请求参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
day |
String | 否 | 要查询是否放假的日期，形如 20260501 |
needDesc |
Number/String | 否 | 是否返回节日简介；传 1 返回当日公众日、国际日与我国传统节日简介，传 2 仅返回法定节假日简介，不传则不返回 |
调用方式以 Authorization: APPCODE <appcode> 鉴权为例（多语言示例中的端点地址请用控制台实际地址替换）：
import requests
APP_CODE = "<your_appcode>" # 控制台获取，勿写入前端
DAY = "20260501"
resp = requests.get(
"/queryHoliday", # 端点地址以控制台实际为准
params={
"day": DAY, "needDesc": 1},
headers={
"Authorization": f"APPCODE {APP_CODE}"},
timeout=5,
)
resp.raise_for_status()
data = resp.json()
print(data["showapi_res_code"], data["showapi_res_body"])
对应返回结构示例（字段含义逐项解释）：
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_body": {
"ret_code": 0,
"day": "20260501",
"holiday": "劳动节",
"type": "3",
"weekDay": 6,
"cn": "周六",
"en": "Saturday",
"begin": "20260501",
"end": "20260505",
"holiday_remark": "5月1日至5日放假调休，共5天，4月26日（周日）上班。",
"h": [
{
"day": "0521", "genus": "public", "name": "世界文化发展日",
"info": "……节日简介……", "lunaDay": "", "origin": "……" }
]
}
}
关键字段说明：
| 字段 | 含义 |
|---|---|
type |
当日类型：1 工作日、2 周末、3 节假日 |
holiday |
节日名称；工作日显示「无」，周末显示「周末」，节假日显示节日名 |
weekDay / cn / en |
星期几的数字、中文、英文名 |
begin / end |
节日或周末的起止日期；工作日时为空串 |
holiday_remark |
调休补班等备注 |
h |
当日节日简介数组；仅当传 needDesc 时返回，无节日时为空 |
5.2 节假日列表
传 year（形如 2026）返回全年节假日数组，每个元素含 begin、end、holiday、holiday_remark 与调休日列表 inverse_days，适合做年度假期规划。
5.3 调休日列表
传 year 返回全年需要补班上班的调休日列表，适合考勤与排班直接取用。
六、在线调试实录
调试建议按「先验网关 → 再验业务 → 最后验场景」的顺序进行。下图为一次完整调试的轨迹示意。
- 在控制台的在线调试入口填入
day=20260501，不传needDesc，确认返回中type、holiday、weekDay、holiday_remark齐全且ret_code为0。 - 再传
needDesc=1，观察h数组是否出现节日简介，验证可选参数行为符合预期。 - 换一个普通工作日（如
day=20260915），确认type为1、begin/end为空串，验证工作日分支。 - 用一个调休补班的周末日期，确认
holiday_remark能体现「某日上班」的提示。
调试中重点核对：showapi_res_code 是否为 0；showapi_res_body.ret_code 是否为 0；日期格式是否严格为 8 位 YYYYMMDD。
七、调用限制与规范
- 日期格式：
day必须为 8 位字符串YYYYMMDD；year为 4 位字符串。格式错误会返回失败结果。 - 数据范围：支持自 2018 年起的历年节假日；次年数据在国务院通知发布后更新，更新频率以接口实际为准。
- 鉴权：统一使用 AppCode（请求头
Authorization: APPCODE <appcode>）或 AppKey 查询参数，凭据泄露后请在控制台及时吊销重发。 - 频次控制：对同一日期的高频重复调用，建议在应用层做短 TTL 缓存（如节假日结果以「日期 + 年份」为 key 缓存整年），降低实际调用量。
- 调用扣减：仅当网关返回状态码
200时计次，非200不计入，调用失败不会产生无效消耗。 - 数据安全：本接口为只读查询，入参为日期，不涉及敏感个人信息；仍建议在日志中对凭据做脱敏处理，不在响应中回显 AppCode。
八、能力边界与免责
- 接口返回的节假日、调休与工作日判定基于历年已发布数据，数据以官方发布与接口实际返回为准。
inverse_days等调休日字段自 2021 年起的数据有值，早年数据可能缺失。- 接口结果可用于日程展示与业务判断，但涉及财务、合规、薪酬等重大决策时，请以官方正式文件为最终依据，接口数据仅供参考。
- 接口不支持对未来未发布通知的年份做节假日预测，仅覆盖已确认的历年数据。
九、错误码排查
先看网关层 showapi_res_code，再看业务层 showapi_res_body.ret_code。常见情况与处理：
| 现象 | 可能原因 | 处理办法 |
|---|---|---|
showapi_res_code 非 0、报鉴权错误 |
AppCode 缺失或拼写错误、请求头名不匹配 | 核对 Authorization: APPCODE <appcode> 格式与凭据有效性 |
showapi_res_code 非 0、限流 |
短时间调用过密 | 降低频次、加指数退避重试与熔断降级 |
ret_code 非 0 |
参数格式错误（day 非 8 位、year 非 4 位） |
校验日期格式后重试 |
返回体为空或缺 h |
未传 needDesc，或当日无节日简介 |
按需传 needDesc=1；无节日时 h 为空属正常 |
| 跨年数据缺失 | 查询年份超出已发布范围 | 确认年份在数据支持范围内 |
| 网关状态码非 200 | 网络或临时故障 | 超时后做有限次重试，失败降级为本地默认规则 |
十、技术 FAQ
Q1：type 到底怎么理解？type 取 1 为工作日、2 为周末、3 为节假日。三者互斥，配合 holiday（节日名或「无」「周末」）可唯一判定当日性质。
Q2：调休补班信息从哪里看？
单查询看 holiday_remark 文字备注；需要整年补班日期时用调休日列表接口传 year，或节假日列表接口取每个元素的 inverse_days。
Q3：为什么要传 needDesc？
节日简介（h 数组）数据量较大，默认不返回以减小响应。日历、资讯类产品需要展示简介时再传 1（全部）或 2（仅法定节假日）。
Q4：数据会不会随通知变化？
会。次年节假日在每年 10 月至 11 月国务院通知发布后更新。对「尚未发布通知」的远期年份，结果可能不完整，请以接口实际返回为准。
Q5：前端能直接调吗？
不建议在前端暴露凭据。更稳妥的做法是改由服务端统一承接对外调用，AppCode 保存在服务端，前端只与你的后端交互。
Q6：同一日期反复调用怎么省？
节假日结果稳定，可按「日期」缓存全年一次查询结果，或按「年份」批量拉取节假日列表后本地判断，显著降低调用量。
十一、内容小结
本文以一个节假日查询接口为主线，覆盖了三类接口的能力对比、单节假日查询的参数与返回字段、多语言调用示例、在线调试顺序、调用规范、能力边界、错误码与常见问题。核心要点：
- 用
day（8 位日期）查询，type判定工作日 / 周末 / 节假日，holiday、holiday_remark给出节日名与调休备注，needDesc可选返回节日简介。 - 年度需求用节假日列表与调休日列表接口（
year）一次拉取，本地缓存复用。 - 调用统一走
Authorization: APPCODE <appcode>鉴权，凭据仅存服务端、日志脱敏。 - 数据自 2018 年起、次年 10—11 月更新；结果可展示、可判断，重大决策以官方文件为准。
