在日程应用、考勤系统与交易日历里,经常需要判断某一天是否放假、属于哪种日期类型,以及某一年有哪些调休补班日。节假日查询 API 把这类日期判定能力封装为接口调用:传入一个日期或年份,即可拿到结构化的节假日信息。本文围绕三类查询接口,整理参数设计、多语言调用示例、返回字段解读、在线调试走查与错误排查要点,帮助读者完成从鉴权到业务字段解析的接入过程。
一、技术简介
节假日查询 API 是一组面向日期判定场景的数据接口,提供三类能力:按年份查询整年的节假日列表、按具体日期核验当天是否为节假日、按年份查询整年的调休补班日清单。接口通过阿里云市场 API 网关对外提供,请求方式为 GET,返回类型为 JSON。调用方在请求头中携带 Authorization: APPCODE <appcode> 完成身份认证,网关据此完成鉴权与调用次数计量。
从数据形态看,三类接口返回的都是结构化字段:日期区间用 8 位字符串表示(如 20221001),日期类型用枚举值表示(1 为工作日、2 为周末、3 为节假日),调休安排用数组逐项描述。这类数据便于直接写入日历渲染、排班规则或任务调度逻辑,无需调用方再做文本解析。
二、能力概览
三类接口覆盖的查询维度与返回内容如下表所示。
| 接口 | 主要入参 | 返回内容 | 适用情形 |
|---|---|---|---|
| 节假日列表 | year(年份) | 全年节假日清单:起止日期、节日名称、放假说明、调休补班日 | 年度日历初始化、批量导入 |
| 节假日查询 | day(日期)、needDesc(是否返回简介) | 单日类型、节日名称、星期、假期区间、当日节日简介 | 单日核验、日期类型判断 |
| 调休日列表 | year(年份) | 全年调休补班日清单:调休名称、起止日期 | 排班提醒、考勤工时核算 |

三个接口可以组合使用:先用年度接口拉取全年数据做本地缓存,再用单日接口处理实时核验请求,可减少网关调用次数并降低对端侧的实时性依赖。
三、适用场景
节假日数据的技术用途,主要体现为「日期 → 类型/名称/区间」的结构化转换,以及由此派生出的业务规则。
在日程与待办应用中,日历渲染阶段可按年拉取节假日列表,把休市、放假与补班日高亮为不同颜色;用户新建日程时调用单日核验接口,提示当天是否为工作日。数据流向是「year → 年度节假日表 → 日历渲染」。
在考勤与排班系统中,可先获取全年调休日清单写入排班规则,再对打卡日期核验 type 字段,区分法定节假日、周末与补班日,作为工时统计的输入。数据流向是「year → 调休清单 → 考勤规则引擎」。
在证券与交易日历场景中,可结合节假日与调休清单生成休市日表,对指定交易日核验日期类型,过滤非交易日供行情任务调度使用。数据流向是「day → type 判定 → 交易日调度」。

四、接入流程
接入过程分为开通、鉴权、构造请求、发起调用与解析响应五个环节。

4.1 请求参数
三个接口均为 GET 请求,参数放在 Query 中,请求头只需携带鉴权字段。
| 接口路径 | 参数名 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|---|
| /holidayList | year | string | 否 | 要查询节假日列表的年份 | 2022 |
| /queryHoliday | day | string | 否 | 要查询是否放假的日期(8 位) | 20210501 |
| /queryHoliday | needDesc | string | 否 | 是否返回当日节日简介,传 1 表示需要,默认不返回 | 1 |
| /your_inversday | year | string | 否 | 按年检索调休日的年份 | 2022 |
参数虽标注为非必填,但实际调用时应至少传入
year或day之一,否则查询缺少目标维度。日期与年份的格式要求见 4.2 节。
4.2 参数格式约定
- 年份:4 位数字,如
2022。 - 日期:8 位数字,格式为
yyyyMMdd,如20210501。缺位补零,例如 2022 年 1 月 5 日写作20220105。 - needDesc:
1表示返回节日简介数组h;不传或传其他值时该数组缺省,可减小响应体体积。 - 鉴权头:
Authorization: APPCODE <appcode>,其中 appcode 为调用凭证,应在服务端保存,避免写入前端代码或公开仓库。
4.3 标准调用步骤
- 在控制台开通服务,获取 appcode。
- 根据查询目标选择接口:年度列表、单日核验或调休清单。
- 按格式约定构造 Query 参数。
- 在请求头填入鉴权字段,发起 GET 请求。
- 检查响应中的业务返回码
ret_code,为 0 时再解析业务字段。
五、调用示例与返回结构
下面给出四种语言的调用示例,统一使用 appcode 鉴权。示例中的 host 为网关域名,path 为接口路径。
5.1 Java 示例
import java.util.HashMap;
import java.util.Map;
import com.aliyun.api.gateway.demo.util.HttpUtils;
public class HolidayQuery {
public static void main(String[] args) {
String host = "https://jiejiari.market.alicloudapi.com";
String path = "/queryHoliday";
String method = "GET";
String appcode = "YOUR_APPCODE";
Map<String, String> headers = new HashMap<String, String>();
headers.put("Authorization", "APPCODE " + appcode);
Map<String, String> querys = new HashMap<String, String>();
querys.put("day", "20210501");
querys.put("needDesc", "1");
try {
HttpResponse response = HttpUtils.doGet(host, path, method, headers, querys);
System.out.println(EntityUtils.toString(response.getEntity()));
} catch (Exception e) {
e.printStackTrace();
}
}
}
5.2 Python 示例
import requests
host = "https://jiejiari.market.alicloudapi.com"
path = "/queryHoliday"
appcode = "YOUR_APPCODE"
resp = requests.get(
host + path,
params={
"day": "20210501", "needDesc": "1"},
headers={
"Authorization": "APPCODE " + appcode},
timeout=10,
)
payload = resp.json()
if resp.status_code == 200 and payload.get("showapi_res_body", {
}).get("ret_code") == 0:
body = payload["showapi_res_body"]
print(body["type"], body["holiday"], body["holiday_remark"])
5.3 JavaScript 示例(Node.js)
const https = require("https");
const appcode = "YOUR_APPCODE";
const url = "https://jiejiari.market.alicloudapi.com/queryHoliday"
+ "?day=20210501&needDesc=1";
https.get(url, {
headers: {
Authorization: "APPCODE " + appcode } }, res => {
let raw = "";
res.on("data", chunk => (raw += chunk));
res.on("end", () => {
const payload = JSON.parse(raw);
const body = payload.showapi_res_body || {
};
if (body.ret_code === 0) {
console.log(body.type, body.holiday, body.begin, body.end);
}
});
}).on("error", console.error);
5.4 PHP 示例
<?php
$host = "https://jiejiari.market.alicloudapi.com";
$path = "/queryHoliday";
$appcode = "YOUR_APPCODE";
$query = http_build_query(["day" => "20210501", "needDesc" => "1"]);
$ch = curl_init($host . $path . "?" . $query);
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ["Authorization: APPCODE " . $appcode],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
]);
$result = curl_exec($ch);
curl_close($ch);
$payload = json_decode($result, true);
$body = $payload["showapi_res_body"] ?? [];
if (($body["ret_code"] ?? -1) === 0) {
echo $body["type"], " ", $body["holiday"], PHP_EOL;
}
5.5 返回结构解读
单日核验接口的成功响应主体如下(节选)。
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "5f6462c48d57bae01000c335",
"showapi_res_body": {
"ret_code": 0,
"holiday": "劳动节",
"day": "20210501",
"type": "3",
"weekDay": 6,
"cn": "周六",
"en": "Saturday",
"begin": "20210501",
"end": "20210503",
"holiday_remark": "5月1日—5月3日放假,共3天,5月8日(星期六)要上班。",
"h": [
{
"day": "0521",
"name": "世界文化发展日",
"genus": "public",
"lunaDay": "",
"info": "节日简介文本……"
}
]
}
}
关键字段含义如下。
| 字段 | 含义 | 取值/示例 |
|---|---|---|
| type | 日期类型 | 1 工作日、2 周末、3 节假日 |
| holiday | 节日名称 | 劳动节 |
| weekDay / cn / en | 星期序号 / 中文 / 英文 | 6 / 周六 / Saturday |
| begin / end | 假期起止日期 | 20210501 / 20210503 |
| holiday_remark | 放假与调休说明文本 | 含放假天数与补班日 |
| h[] | 当日节日数组(needDesc=1 时) | name、genus、info、lunaDay |
genus 取值 public 表示公众日或国际日,traditional 表示传统节日;lunaDay 为农历日期,没有对应值时为空字符串。

年度调休清单接口的返回主体为 inverse_days 数组,每项含 name(调休名称)、begin(起始日期)、end(结束日期)。同一节日可能出现多段调休,需要按数组逐项处理,例如劳动节在多份记录中出现。

六、在线调试实录
以核验 2021 年 5 月 1 日为例,走查一次完整调试过程。
第一步,确定入参维度。 目标是判断某一天是否为节假日,因此选用单日核验接口,传入 day=20210501。由于还想拿到当日节日简介,补充 needDesc=1。
第二步,设置鉴权并发送。 在请求头加入 Authorization: APPCODE <appcode>,发起 GET 请求。appcode 通过环境变量注入,不写入调试脚本。
第三步,检查响应。 先看 HTTP 状态码是否为 200,再看 showapi_res_code 与 showapi_res_body.ret_code 是否均为 0。两者都为 0 才进入字段解析。
第四步,解读业务字段。 type=3 表示当天为节假日,holiday=劳动节,begin=20210501、end=20210503 给出假期区间,holiday_remark 给出放假天数与补班日说明。h 数组返回了当日对应的国际日条目。
第五步,异常定位。 若返回码非 0,先核对日期格式是否为 8 位、年份是否为 4 位,再检查 appcode 是否有效、是否已完成开通,最后对照错误码表定位。

调试时建议把一次成功响应保存为固定样本,作为单元测试的基准数据;后续升级鉴权方式或改造解析逻辑时,可用该样本验证输出是否一致。
七、接口调用限制与规范
调用限制以控制台实时配置为准,接入时应遵循以下通用规范。
| 维度 | 说明 |
|---|---|
| 调用次数 | 按接口调用次数计量,仅当 HTTP 响应状态码为 200 时计入,非 200 不计入 |
| 余量提醒 | 余量降至阈值或耗尽时会触发通知,提醒频率与阈值以控制台配置为准 |
| 频率控制 | 单账户存在 QPS 上限,高并发场景应做客户端限流 |
| 参数格式 | 日期 8 位、年份 4 位,格式错误会导致查询无结果 |
| 鉴权要求 | 必须在请求头携带有效 appcode,密钥不得写入前端或公开仓库 |
在工程实践中,建议对结果做本地缓存:年度列表与调休清单的数据在一年内变化很少,可按年缓存;单日核验结果可按日缓存。这样既能减少网关调用次数,也能在短暂网络异常时保持业务可用。对失败请求采用有上限的重试,并配合超时控制与熔断降级,避免故障时的重试风暴。
八、能力边界与免责声明
接口返回的数据用于技术场景中的日期判定与信息展示,理解其边界有助于合理使用。
| 能力范围 | 说明 |
|---|---|
| 支持 | 按年份查询节假日列表、按日期核验类型与节日信息、按年份查询调休补班日 |
| 不支持 | 跨年份自定义时间段的组合查询、单接口一次返回全部历史年份数据、按地区返回地方性假期 |
| 数据边界 | 节日简介为通用信息文本,lunaDay 在无对应农历日期时为空 |
| 格式边界 | 日期与年份需符合位数要求,超出支持范围的年份可能返回空结果 |
数据仅供参考,不构成业务决策的唯一依据。涉及考勤结算、交易日历等关键场景时,应将接口结果与内部规则交叉核对;因直接使用返回结果所产生的业务影响,需由接入方自行评估与承担。
九、错误码与排查指南
响应分为网关层与业务层两层:先看 HTTP 状态码,再看 showapi_res_code 与 showapi_res_body.ret_code。下表列出常见异常类别,具体码值以接口返回与控制台说明为准。
| 异常类别 | 可能原因 | 解决办法 |
|---|---|---|
| 参数错误 | 日期非 8 位、年份非 4 位、参数名拼写错误 | 按格式约定重新构造参数 |
| 鉴权失败 | 请求头缺失或 appcode 无效 | 检查 Authorization 头与凭证是否正确 |
| 权限不足 | 服务未开通或调用次数已耗尽 | 在控制台确认开通状态与余量 |
| 频率受限 | 单位时间请求过多,触发 QPS 限制 | 客户端限流并采用结果缓存 |
| 无数据 | 查询年份超出支持范围或维度缺失 | 核对年份/日期,补充必要入参 |
| 请求超时 | 网络抖动或服务端暂时不可用 | 设置有上限的重试与超时时间 |
| 结果解析失败 | 未按两层返回码判断,直接读取业务字段 | 先判 ret_code 为 0 再解析 |
排查时可按「状态码 → 网关返回码 → 业务返回码 → 字段内容」的顺序逐层定位,避免把鉴权问题误判为数据问题。
十、常见问题 FAQ
Q1:一个接口能查到哪些信息?
三类接口分别覆盖年度节假日列表、单日类型核验与年度调休清单。单日核验可返回日期类型、节日名称、星期、假期起止区间,传入 needDesc=1 时还会返回当日节日简介数组。
Q2:日期类型 type 怎么读?type 为字符串枚举:1 表示工作日,2 表示周末,3 表示节假日。解析时按枚举映射成业务标签,不要直接用字符串大小比较。
Q3:为什么没有返回节日简介?
简介数组 h 需要传 needDesc=1 才返回。未传该参数时数组缺省,这是预期行为,不是数据缺失。
Q4:接口数据刷新频率如何?
年度节假日与调休安排通常在对应年份到来前公布,年内变动较少。具体刷新时间以数据源公布为准,建议在年度切换时重新拉取一次并更新本地缓存。
Q5:能否在高并发场景使用?
可以,但需要配合客户端限流、结果缓存与失败重试策略。年度数据建议本地缓存,实时核验请求按日缓存,减少对网关的重复调用。
Q6:鉴权密钥放在哪里合适?
appcode 应保存在服务端环境变量或密钥管理系统中,由服务端统一转发请求,不要写入前端代码、客户端包或公开代码仓库。
十一、内容小结
节假日查询 API 提供按年与按日两类查询维度,覆盖节假日列表、单日类型核验与调休补班日清单三类能力。接入要点可以归纳为四条:按目标选择接口并构造合规参数;在服务端安全保存 appcode 并完成鉴权;按「状态码 → 网关返回码 → 业务返回码」的顺序判断响应;对年度数据做本地缓存以降低调用频次。
理解 type 枚举、begin/end 日期区间与 h[] 节日数组的字段含义,是把接口数据正确接入日历渲染、排班规则或交易日历的前提。遇到异常时按分层排查思路定位,可显著缩短调试时间。
标签:节假日查询、API接入、接口调用、鉴权、错误排查