引言使用场景该 API 适用于以下典型场景企业考勤与排班系统自动识别工作日与调休日避免人工维护假日表。节假日提醒应用在日期接近假期时向用户推送通知。日历插件或提醒服务动态获取未来年份的放假日期用于 UI 展示或逻辑判断。数据分析统计节假日对业务量的影响例如电商大促期间的流量波动。接口能力边界项目说明接口名称中国法定节假日slugholiday请求方法GET请求地址https://v1.apizero.cn/api/holiday覆盖范围2020–2030 年QPS 限制20 次/秒鉴权方式在 HTTP 头X-API-Key中传递 API Key返回格式JSON该接口仅支持查询全部年份的节假日安排不支持按年份或月份过滤。如需要按特定年份查询需在客户端侧对返回结果自行过滤。请求参数与鉴权参数本接口没有任何 URL 查询参数Query String所有请求均通过 GET 方法发送至固定端点。鉴权调用时必须携带X-API-Key请求头值为申请到的 API Key由字母数字组成。如果缺少该头或 Key 无效服务端会返回 401 错误。RESTful 风格示例GET /api/holiday HTTP/1.1 Host: v1.apizero.cn X-API-Key: YOUR_API_KEY_HERE最小可运行 curl 示例以下 curl 命令可以直接在终端中执行请将YOUR_API_KEY_HERE替换为实际 Keycurl -sS \ -X GET \ -H X-API-Key: YOUR_API_KEY_HERE \ https://v1.apizero.cn/api/holiday-sS表示静默模式但保留错误输出-X GET显式指定 HTTP 方法GET 为默认值可省略-H添加自定义请求头。执行成功后将返回类似以下内容已格式化{ code: 200, message: success, data: [ { date: 2024-01-01, name: 元旦, isOffDay: true, holiday: 元旦 }, { date: 2024-01-02, name: 元旦, isOffDay: false, holiday: 元旦 } ] }注意以上data数组中的字段如isOffDay、holiday仅为示例推测实际返回结构请以官方文档为准。本文重点演示调用流程不保证字段名称完全匹配。代码接入示例Python为了体现“最小可运行”下面给出一个 Python 脚本仅依赖标准库urllib.request无需第三方包import json import urllib.request API_URL https://v1.apizero.cn/api/holiday API_KEY YOUR_API_KEY_HERE # 替换为真实 Key req urllib.request.Request(API_URL) req.add_header(X-API-Key, API_KEY) try: with urllib.request.urlopen(req) as response: data json.loads(response.read().decode()) print(状态码:, data.get(code)) print(消息:, data.get(message)) # data.get(data) 为节假日列表 holidays data.get(data, []) for item in holidays[:5]: # 打印前5条 print(item) except urllib.error.HTTPError as e: print(HTTP错误:, e.code, e.reason) except Exception as e: print(其他错误:, e)运行该脚本如果 Key 有效会输出类似状态码: 200 消息: success {date: 2024-01-01, name: 元旦, isOffDay: True, holiday: 元旦} ...拓展使用 requests 库更简洁若项目已安装requests代码可以更精简import requests resp requests.get( https://v1.apizero.cn/api/holiday, headers{X-API-Key: YOUR_API_KEY_HERE} ) resp.raise_for_status() # 非 200 将抛出异常 result resp.json() print(result)返回值结构解读成功响应的 JSON 顶层包含三个字段字段类型说明codeint业务状态码200 表示成功messagestring状态描述成功时为successdataarray节假日数据列表每个元素是一个对象data数组中的每个对象代表一天放假或调休具体字段以官方文档说明为准。按照常见实践这些字段可能包括date日期字符串格式YYYY-MM-DDname节日名称如 元旦isOffDay是否放假true表示放假false表示调休上班holiday所属节日名称与name可能相同或为 元旦、春节 等如需判断某天是否为工作日可以遍历data并根据isOffDay判断。若某天不在列表中则默认视为工作日。常见错误处理HTTP 状态码可能原因排查思路401API Key 缺失或无效检查X-API-Key头是否正确设置确认 Key 未过期。403请求被拒绝可能 IP 被限制或调用超过 QPS 上限。429请求过于频繁降低调用频率QPS 限制为 20建议加本地重试及指数退避。500服务端内部错误稍后重试若持续出现可反馈给平台。在代码中应该捕获urllib.error.HTTPError或requests.exceptions.HTTPError并根据状态码做出相应处理。工程化注意事项1. API Key 管理不要将 Key 硬编码在代码仓库中应通过环境变量或配置服务注入。示例配置.envHOLIDAY_API_KEYyour_key_here在代码中读取os.getenv(HOLIDAY_API_KEY)2. 缓存策略节假日数据在较长周期内一年不会变更且接口返回全量数据非常适合缓存。建议缓存时长至少 1 小时甚至可以按天缓存。缓存介质对于单机应用可用内存或本地文件对于分布式服务可用 Redis。更新时机每年年底新假期公布时手动或定时刷新一次缓存。3. 重试与熔断当遇到 5xx 错误或网络超时时应实现重试机制。推荐采用指数退避Exponential Backoff例如重试 3 次间隔分别为 1s、4s、9s。同时注意不要超过 QPS 限制。4. 数据校验接口返回的data可能包含 500 条记录建议在消费前校验code是否为 200并检查data是否为列表。避免因数据异常导致程序意外中断。5. 时间处理返回的日期字符串统一为YYYY-MM-DD格式使用时建议转换为datetime.date对象以便比较。如果涉及时区中国使用东八区需确保服务器时间设置正确。总结本文通过一个最小可运行的 curl 命令演示了中国法定节假日 API 的调用方法。随后扩展了 Python 代码示例并详细解析了返回结构、错误处理及工程化注意事项。该接口数据稳定、调用简单适合快速集成到各类日历、排班项目中。开发者无需手动维护假日表只需关注业务逻辑即可。参考文档官方文档页https://apizero.cn/aidocs/holiday原始 Markdown 文档https://apizero.cn/aidocs/holiday/raw.mdAPI 基础地址https://v1.apizero.cn/api/holiday鉴权方式HTTP HeaderX-API-Key请务必查阅官方文档以获取最新的字段定义和更新日志。
