节假日查询API接口|输入日期或年份,返回日期类型、节日名称与调休补班日

简介: 接入节假日查询接口时常被日期格式、日期类型枚举与调休字段困扰?本文给出参数设计、四种语言调用示例与错误排查清单。覆盖节假日列表、单日核验与调休日清单三类接口,梳理 year、day、needDesc 入参约定,解读 type、holiday、holiday_remark 与 inverse_days 返回字段,并附在线调试走查、调用限制规范与能力边界说明,帮助开发者完成从鉴权到业务字段解析的接入。

在日程应用、考勤系统与交易日历里,经常需要判断某一天是否放假、属于哪种日期类型,以及某一年有哪些调休补班日。节假日查询 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 标准调用步骤

  1. 在控制台开通服务,获取 appcode。
  2. 根据查询目标选择接口:年度列表、单日核验或调休清单。
  3. 按格式约定构造 Query 参数。
  4. 在请求头填入鉴权字段,发起 GET 请求。
  5. 检查响应中的业务返回码 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接入、接口调用、鉴权、错误排查

相关文章
|
6天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
7111 17
|
6天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
2360 10
|
8天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
8天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
4天前
|
传感器 安全 区块链
Windows 电脑运行安卓应用教程:开源工具 ApkStart 双击 APK 即装、独立窗口运行
ApkStart 是一款开源Windows工具,让安卓APP像原生软件一样运行:双击APK即安装、生成真实图标、独立窗口启动、开始菜单可搜索。无需传统模拟器,内置QEMU运行时,支持数据互通、ARM兼容与命令行操作。(239字)
|
21天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
10269 59
|
4天前
|
人工智能 弹性计算 开发工具
零成本玩各大模型!DeepSeek Harness dsh-our-free-model 插件,13 个厂商模型直接用
总结一下:装这个插件,你不用注册、不用绑卡、不用填一个 Key,就能在 DeepSeek Harness 里用上 DeepSeek V4.1 Flash、Kimi K3 这一批前沿模型,而且是白嫖的、还不限量。三步搞定:下载插件,复制包含 `package.json` 的插件目录路径,在「添加插件」里粘贴路径安装并重启。无论是在阿里云 ECS 上通过命令行部署的 Web 版,还是本地的 Electron 桌面端,都能顺利跑通,快速搭建一套零成本的免费模型使用环境。
1066 1
|
7天前
|
Linux API iOS开发
【DSH】DeepSeek Harness新手保姆教程(下载+安装+配置+使用,2026最新实测)
DeepSeek Harness(dsh)是DeepSeek AI开源的智能体框架,秉持“一切皆插件”理念,支持读文件、改代码、跑命令、处理表格、联网搜索等操作。免费开源,兼容Windows/macOS/Linux,提供桌面端与网页端,可灵活安装插件扩展能力。
|
16天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
3512 9