节假日查询

查询指定日期的节假日/工作日状态，支持调休识别

按日期查询法定节假日、调休补班与周末判定，内置国务院官方放假安排（当前覆盖 2026 年），未收录年份自动回退周末判定。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/tool-holiday/holiday JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
date	string	否	查询日期，格式 YYYY-MM-DD，不传则默认当天

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	提示信息
data.date	string	查询日期
data.weekday	string	星期几（星期一~星期日）
data.is_weekend	boolean	是否周末
data.is_holiday	boolean	是否法定节假日
data.holiday_name	string	节假日名称，非节假日为 null
data.is_workday	boolean	是否工作日
data.workday_type	string	工作日类型：normal 正常工作日 / swap 调休补班 / holiday 节假日
data.swap_for	string	调休补班对应的节假日，无则为 null
data.mode	string	数据模式：official 官方节假日数据 / weekend 周末兜底模式
data.year_official	boolean	是否使用官方节假日数据；false 表示该年份未收录，按周末兜底判定

请求示例

返回示例

{"msg":"success","code":200,"data":{"date":"2026-10-01","mode":"official","weekday":"星期四","swap_for":null,"is_holiday":true,"is_weekend":false,"is_workday":false,"holiday_name":"国庆节","workday_type":"holiday","year_official":true}}

产品说明

产品概述

法定节假日与工作日查询，支持调休上班日识别，未收录年份自动回退周末判定。

使用场景

数据查询：快速集成节假日/工作日查询到您的应用中

业务系统：将节假日/工作日查询数据嵌入业务流程

开发工具：通过 API 接口获取生活服务数据

数据分析：基于节假日/工作日查询数据进行分析和决策

费用计算

按次计费单价

¥0.001 / 次

每次调用接口从账户余额中扣除相应费用，VIP 用户可享折扣

扣费优先级

免费额度

次数包

余额扣费

计费方式详解

1 免费额度

· 接口每日免费额度已关闭
· VIP 用户月度免费额度：
· 个人版：每月 5000 次，本接口月上限 5000 次
· 专业版：每月 30000 次，本接口月上限 30000 次
· 企业版：每月 200000 次，本接口月上限 200000 次
· 账户如有注册/活动赠送的免费次数，会优先于接口免费额度扣减
· VIP 月度免费额度仅适用于单次售价不高于 ¥0.0800/次的接口；接口每日免费额度按接口配置执行
VIP 月度免费额度每月重置，未使用部分不累计至下月。

2 次数包

预付费购买固定调用次数，折算单价与按次付费相同，用完为止。
次数包为独立计费，不与 VIP 折扣叠加。
请在有效期内使用，过期后未使用的次数不可再用。

3 余额扣费

按次从账户余额扣除费用；所有用户可享量折扣，VIP 用户额外享 VIP 折扣。
扣费公式：实际扣费 = 接口单价 × (1 - VIP 折扣比例 - 量折扣比例)，并受总折扣上限和最低利润率保护约束
VIP 折扣：个人版9折专业版8折企业版7折
量折扣：月付费调用 ≥1000 次享 2%、月付费调用 ≥10000 次享 5%、月付费调用 ≥20000 次享 10%
· 量折扣按账号当月全部接口的付费调用次数统计，达到更高档位时按更高档位计算
总折扣上限：VIP 折扣 + 量折扣合计不超过 50%
最低利润率保护：折后价不得低于成本价 × (1 + 15%)；若接口售价本身低于该保护价，则取消折扣并按售价计费
余额不足时调用将失败，请及时充值。

次数包方案

方案名称	调用次数	价格	折算单价	比按次付费节省	有效期
标准次数包	10000 次	¥90	¥0.0090/次	-	365 天

VIP 权益对比

等级	每月免费次数	本接口月免费上限	折扣	VIP 折后单价
免费版	按接口配置	—	-	¥0.001/次
个人版	5000 次	5000 次	10%	¥0.0009/次
专业版	30000 次	30000 次	20%	¥0.0008/次
企业版推荐	200000 次	200000 次	30%	¥0.0007/次

* VIP 月度免费额度每月重置。每月免费次数为账号级 VIP 月额度，本接口月免费上限为其中对本接口的限制（接口可单独设置上限或关闭）。VIP 折扣仅适用于余额扣费方式，VIP 折后单价不含量折扣。本接口已关闭接口级月度免费额度（不影响 VIP 月度免费额度）。接口每日免费额度已关闭。

费用计算示例

* 以下示例未包含量折扣，量折扣按账号当月全部接口的付费调用量另行计算。

示例1：普通用户按次付费

调用 1000 次，费用 = 0.001 × 1000 = ¥1.00

示例2：个人版用户按次付费（仅 VIP 折扣，已考虑最低利润率保护）

调用 1000 次，折扣约 10%，费用 = 0.001 × (1 - 10%) × 1000 ≈ ¥0.90

错误码说明

错误码	说明	解决方案
200	请求成功	-
400000	请求参数错误	检查参数名、格式与取值；具体原因见响应 msg
401000	认证失败	检查 Authorization: Bearer 密钥是否正确、是否过期
402000	账户余额不足	充值后重试
403000	无访问权限	确认密钥权限、接口范围与 IP 白名单是否满足要求
404001	接口或端点不存在	检查 API 与端点的请求路径
409000	请求冲突	请稍后重试
422000	参数校验失败	检查参数格式与取值
429000	请求频率或额度超限	降低调用频率，或升级套餐提升额度
500000	服务器内部错误	携带响应中的 request_id 联系技术支持
502000	服务暂时不可用	稍后重试
503000	服务暂时不可用	稍后重试
504000	请求超时	稍后重试

更新日志

暂无更新日志