使用须知
- 1、这是由本人用业余时间开发的基于ThinkPHP 8的中国法定节假日API，免费提供给同样需要的人。
- 2、节假日信息我会尽快更新，如果发现某个节假日配置错误或没有配置，请联系我的QQ或留言反馈。
- 3、有其它需求也可以联系我，付费定制，预付款70%，价格可商议。
- 4、网站永久维护更新，放心使用，但请别乱用，带宽有限，请谅解。
联系方式
- QQ：66257875
- 邮箱：Jack.Liu@ailcc.com (PS：邮箱联系更快)
近期更新 -- API接口优化 2026-01-07 16:23:57
- 1、优化接口限流返回逻辑，限流时返回 HTTP 状态码
429，避免客户端将受限请求误识别为正常响应。 - 2、将接口缓存驱动由原有方式调整为 Redis，实现跨进程共享缓存，提高缓存命中率及多进程环境下的数据一致性。
常见问题
- 1、节假日 api 不支持HTTP调用，必须是HTTPS。
- 2、网站使用白名单加访问IP进行访问限制，域名、IP未在白名单中的，接口每分钟仅允许查询31次，24小时最多可查询14400次（所有接口的总计查询次数）。
- 3、注册用户或白名单域名、IP不受访问次数的限制。
- 4、白名单必须配合Token使用，支持 Header Token、URL Token 使用，建议选用 Header Token。
URL/xxx?token=xxx
HEADER: X-API-TOKEN: xxx限额说明及规则
- 1、以下限额都是按照每个用户的域名或IP统计的，注册用户最多允许1个域名/IP。
- 2、免费用户所有接口限额时间为 24 小时，每天凌晨00:01重置状态。
- 3、免费用户节假日 API 接口24小时内总计限额为 14400次/IP，每分钟限制31次。
- 4、如果限额太少不够用，可以发邮件说明情况，确定如为合理需求，可以提高额度。
- 5、免费用户限额目的是为了大家都能平均分配，保证访问速度。
API接口说明文档
苹果设备订阅法定节假日 - ICS
苹果官方已有中国法定节假日订阅，非必要不建议订阅本站日历，因为本站日历中包含24节气、其它节气及民俗节日等信息。
可以注册用户，自行添加个人日历，订阅自己的日历，订阅时默认会将系统日历一起订阅（可以关闭系统日历）。
也只可以只订阅本站默认的万年历，该订阅无需注册即可订阅。
接口地址： GET https://holiday.ailcc.com/api/holiday/ics
接口功能： 返回一个可供苹果日历、Google 日历、Outlook 等日历软件订阅的 ICS（iCalendar）日历文件，其中包含 “法定节假日、调休放假、补班” 的日期信息。
使用办法：该接口不需要任何参数，直接在设备上的日历中 订阅 即可。
日历说明：服务器会自动返回当前年份 + 下一年份的节假日 ICS 内容，只更新近2年的日历。
日历更新：日历数据每次访问均为最新版本，用于保证订阅端能够自动更新。
接口包含：X-APPLE-CALENDAR-COLOR:#FF3333
X-WR-CALNAME:中国法定节假日
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//AILCC//Chinese Holiday API//CN
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-APPLE-CALENDAR-COLOR:#FF3333
X-WR-CALNAME:中国法定节假日
BEGIN:VEVENT
UID:0da98bb11fe3f47c6b25c43014668bb6@ailcc.com
DTSTART;VALUE=DATE:20250101
DTEND;VALUE=DATE:20250101
SUMMARY:元旦（休）
DESCRIPTION:元旦（休）
END:VEVENT
BEGIN:VEVENT
UID:395865170ccabb58554e436e264fd40b@ailcc.com
DTSTART;VALUE=DATE:20250201
DTEND;VALUE=DATE:20250201
SUMMARY:春节（休）
DESCRIPTION:春节（休）
END:VEVENT
END:VCALENDAR
📱 订阅方式：
- iPhone / iPad：打开“日历”app，点屏幕下方中间的“日历”，再点左下角“添加日历”，选择“添加订阅日历”，粘贴URL，点订阅。
- Mac：日历 → 文件 → 新建日历订阅 → 输入地址。
获取指定日期的节假日信息 - info
接口地址：GET https://holiday.ailcc.com/api/holiday/info/$date
@params $date: 指定日期的字符串，格式 ‘2025-10-01’。可以省略，则默认服务器的当前时间。
@params extra：是否返回日期辅助表信息，默认不返回。可选值：’Y’ 返回，’N’ 不返回。
@return json: 如果不是节假日或周末，holiday字段为null。
{
"code": 0, // 0服务正常。-1服务出错
"type": {
"type": enum(0, 1, 2, 3，4), // 节假日类型，分别表示 工作日、周末、节日、调休放假、补班。
"name": "国庆节（休）", // 节假日类型中文名，可能值为 周一 至 周日、假期的名字、某某调休。
"week": 3 // 一周中的第几天。值为 1 - 7，分别表示 周一 至 周日。
"cnLunar": "八月初十", // 农历
"extra_info": "" // 其它节气
},
"holiday": {
"holiday": true, // true表示是节假日，false表示是调休。
"name": "国庆节（休）", // 节假日的中文名。如果是调休，则是调休的中文名，例如“国庆节（休）”。
"wage": 3, // 薪资倍数，1表示是1倍工资，该数据不再详细维护。
"date": "2025-10-01", // 查询的时间参数。
"after": null, // 只在调休或补班下有该字段。1表示假后调休或补班，0表示假前调休或补班，否则为null。
"target": "国庆节", // 只在调休下有该字段。表示调休的节假日，否则为null。
"rest": 39 // 表示当前时间距离目标还有多少天。
},
"extra_infos": [ // 辅助表信息，站长自用，默认不展示
{
"title": "测试标题",
"value": "测试内容"
}, {
"title": "测试标题1",
"value": "测试内容2"
},
]
}示例：
https://holiday.ailcc.com/api/holiday/info/2025-10-01
https://holiday.ailcc.com/api/holiday/info/2025-10-1
https://holiday.ailcc.com/api/holiday/info/2025-10-1?extra=Y
批量查询指定日期节假日信息 - batch
接口地址：GET https://holiday.ailcc.com/api/holiday/batch?d=$date&type=Y
@params d: 指定日期的字符串，多个日期之间使用且只能使用英文逗号“,”连接。最大长度查询个数50，格式 ‘2025-10-01’。
@params type: 是否返回日期类型，默认不返回。可选值：’Y’ 返回，’N’ 不返回。
@return json: 返回以日期为key的对象。
{
"code": 0, // 0服务正常。-1服务出错
"holiday": { // 传过来的日期是什么，key就是什么。传多少个就有多少个。
"2025-09-29": null, // 如果不是节假日，则为null
"2025-10-08": { // holiday的值都是一致的
"holiday": true, // true表示是节假日，false表示是调休。
"name": "国庆节（休）", // 节假日的中文名。如果是调休，则是调休的中文名，例如“国庆节（休）”。
"wage": 1, // 薪资倍数，1表示是1倍工资，该数据不再详细维护。
"date": "2025-10-08", // 查询的时间参数。
"rest": 1 // 表示当前时间距离目标还有多少天。
}
},
"type": { // 只有明确指定参数 type=Y 时才返回类型信息
"2025-09-29": { // 一一对应holiday对象的key，holiday有多少个这里就有多少个
"type": enum(0, 1, 2, 3，4), // 节假日类型，分别表示 工作日、周末、节日、调休放假、补班。
"name": "周一", // 节假日类型中文名，可能值为 周一 至 周日、假期的名字、某某调休。
"week": 1 // 一周中的第几天。值为 1 - 7，分别表示 周一 至 周日。
"cnLunar": "七月十八", // 农历
"extra_info": "" // 其它节气，一般为空
},
"2025-10-08": {
"type": 2,
"name": "国庆节（休）",
"week": 3
"cnLunar": "八月十七",
"extra_info": "寒露"
}
}
}示例：
https://holiday.ailcc.com/api/holiday/batch?d=2025-9-9
https://holiday.ailcc.com/api/holiday/batch?d=2025-9-9,2025-10-08,2025-03-1&type=Y
获取指定日期的下一个节假日（如果在放假前有调休，也会返回）- next
接口地址：GET https://holiday.ailcc.com/api/holiday/next/$date?type=Y&week=Y
@params $date: 指定日期的字符串，格式“2025-09-27”，日期可以省略，则默认服务器的当前时间。
@params type: 是否返回日期类型，默认不返回。可选值：’Y’ 返回，’N’ 不返回。
@return week: 节假日是否包含周末，默认不包含。可选值：’Y’ 包含周末，’N’ 不包含。
@return json: 返回指定日期的下一个最近的节假日，如果在放假之前要调休，则会一起返回调休的信息。如果包含周末，则节日和周末冲突时，以节日为优先级。 比如特殊情况：周六是调休，则holiday返回周日，workday返回周六。其它情况以此类推，holiday永远会返回下一个节日。
{
"code": 0, // 0服务正常。-1服务出错。
"holiday": {
"holiday": true, // 该字段一定为true。
"name": "国庆节（休）", // 节假日的中文名。
"wage": 3, // 薪资倍数，3表示是3倍工资，该数据不再详细维护。
"date": "2025-10-01", // 节假日的日期。
"cnLunar": "八月初十", // 农历。
"rest": 4 // 表示当前时间距离目标还有多少天。
},
"workday": { // 如果节假日前没调休，则此字段为null。
"holiday": false, // 此字段一定为false。
"name": "国庆节（班）", // 调休的中文名。
"after": null, // 只在调休或补班下有该字段，1表示假后调休或补班，0表示假前调休或补班，否则为null。
"wage": 1, // 薪资倍数，3表示是3倍工资，该字段不在详细维护。
"target": "国庆节", // 表示调休的节假日。
"date": "2025-09-28", // 表示要调休的日期。
"rest": 1 // 表示当前时间距离目标还有多少天。
},
"type": { // 只有明确指定参数 type=Y 时才返回类型信息。
"holiday": { // 对应 holiday 中的日期类型，只有返回 holiday 信息时才存在此日期类型。
"type": enum(0, 1, 2, 3，4), // 节假日类型，分别表示 工作日、周末、节日、调休放假、补班。
"name": "国庆节（休）", // 节假日类型中文名，可能值为 周一 至 周日、假期的名字、某某调休。
"week": enum(1 - 7) // 一周中的第几天。值为 1 - 7，分别表示 周一 至 周日。
"cnLunar": "八月初十", // 农历
"extra_info": "", // 其它节气，一般为空
"date": "2025-10-01" // 当天时间
},
"workday": { // 对应 workday 中的日期类型，只有返回 workday 信息时才存在此日期类型
"type": enum(0, 1, 2, 3，4), // 节假日类型，分别表示 工作日、周末、节日、调休放假、补班。
"name": "国庆节（班）", // 节假日类型中文名，可能值为 周一 至 周日、假期的名字、某某调休。
"week": 7 // 一周中的第几天。值为 1 - 7，分别表示 周一 至 周日。
"cnLunar": "八月初七", // 农历
"extra_info": "", // 其它节气，一般为空
"date": "2025-09-28" // 当天时间
}
}
}示例：
https://holiday.ailcc.com/api/holiday/next/2025-9-9
https://holiday.ailcc.com/api/holiday/next/2025-09-27?type=Y&week=Y
https://holiday.ailcc.com/api/holiday/next/
获取指定日期的下一个工作日（工作日包含正常工作日、调休）不包含当天 - nextWorkday
接口地址：GET https://holiday.ailcc.com/api/holiday/nextWorkday/$date
@params $data:指定日期的字符串，格式“2025-10-01”，时间可以省略，则默认服务器的当前时间。
@return json:返回指定日期的下一个最近的工作日，工作日包含正常工作日、调休，不包含当天。
{
"code": 0, // 0服务正常。-1服务出错
"workday": { // 如果没有查找到最近的工作日，则此字段为null。最大查找长度为30
"type": enum(0, 1, 2, 3，4), // 节假日类型，分别表示 工作日、周末、节日、调休放假、补班。
"name": "工作日", // 工作日类型中文名，可能值为 周一 至 周五、某某调休。
"week": 4, // 一周中的第几天。值为 1 - 7，分别表示 周一 至 周日。
"date": "2025-10-09", // 表示要工作的日期。
"rest": 8 // 表示当前时间距离目标还有多少天。
"extra_info": "", // 其它节气，一般为空
}
}示例：
https://holiday.ailcc.com/api/holiday/nextWorkday/2025-10-01
https://holiday.ailcc.com/api/holiday/nextWorkday/
https://holiday.ailcc.com/api/holiday/nextWorkday/2025-10-1
获取指定年份或年月份的所有节假日信息 - year
接口地址：GET https://holiday.ailcc.com/api/holiday/year/$date
@params $date:指定年份或年月份，格式“2025-10”，“2025-9” 或者“2025”。可以省略，则默认服务器当前时间的年份。
@return type:是否返回日期类型，默认不返回。可选值：’Y’ 返回，’N’ 不返回。
@params week:节假日是否包含周末，默认不包含。可选值：’Y’ 包含周末，’N’ 不包含。
@return json:返回指定年份或年月份的所有节假日，以日期作为key，格式：mm-dd。如果没有该年份或月份，则返回空对象，只返回节假日，不返回任何补班。
{
"code": 0, // 0服务正常。-1服务出错
"holiday": {
"10-01": {
"holiday": true, // 该字段一定为true
"name": "国庆节（休）", // 节假日的中文名。
"wage": 3, // 薪资倍数，3表示是3倍工资，该数据不再详细维护。
"date": "2025-10-01", // 节假日的日期
"cnLunar": "八月初十", // 农历
"extra_info": "", // 其它节气，一般为空
"rest": 39 // 表示当前时间距离目标还有多少天。
},
"10-02": {
"holiday": true,
"name": "国庆节（休）",
"wage": 3,
"date": "2025-10-02",
"cnLunar": "八月十一",
"extra_info": "",
"rest": 40
}
}
"type": { // 只有明确指定参数 type=Y 时才返回类型信息
"2025-10-01": { // 一一对应holiday对象的key，holiday有多少个这里就有多少个
"type": enum(0, 1, 2, 3，4), // 节假日类型，分别表示 工作日、周末、节日、调休放假、补班。
"name": "国庆节（休）", // 节假日类型中文名，可能值为 周一 至 周日、假期的名字、某某调休。
"week": enum(1 - 7) // 一周中的第几天。值为 1 - 7，分别表示 周一 至 周日。
"cnLunar": "八月初十", // 农历
"extra_info": "" // 其它节气，一般为空
},
"2025-10-02": {
"type": 2,
"name": "国庆节（休）",
"week": 4
"cnLunar": "八月十一",
"extra_info": ""
},
"2025-10-03": {
"type": 2,
"name": "国庆节（休）",
"week": 5
"cnLunar": "八月十二",
"extra_info": ""
},
}
}示例：
https://holiday.ailcc.com/api/holiday/year/
https://holiday.ailcc.com/api/holiday/year/2025
https://holiday.ailcc.com/api/holiday/year/2025-10?type=Y&week=Y
获取指定年份里每天的信息 - allyear
接口地址：GET https://holiday.ailcc.com/api/holiday/allyear/$date
@params $date:指定年份2026”，可以省略，则默认服务器当前时间的年份。
@return json:返回指定年份全年每天的信息，以日期作为key，格式：mm，如果没有该年份或月份，则返回当年。
{
"code": 0, // 返回码，0服务正常。-1服务出错
"year": "2026", // 查询的年份（YYYY）
"count": 365, // 当年天数（平年 365，闰年 366）
"data": [
{
"date": "2026-01-01", // 日期（YYYY-MM-DD）
"type": enum(0, 1, 2, 3，4), // 节假日类型，分别表示 工作日、周末、节日、调休放假、补班。
"is_holiday": 1, // 是否为休息日，1 = 放假（周末 / 法定节假日 / 调休），0 = 工作日（含补班）
"name": "元旦节（休）", // 节假日的中文名。如果是调休，则是调休的中文名，例如“国庆节（休）”。
"wage": 1, // 薪资倍数，3表示是3倍工资，该数据不再详细维护。
"after": null, // 只在调休或补班下有该字段。1表示假后调休或补班，0表示假前调休或补班，否则为null。
"week": 4, // 一周中的第几天。值为 1 - 7，分别表示 周一 至 周日。
"target": "元旦节", // 只在调休下有该字段。表示调休的节假日，否则为null。
"lunar": "冬月十三", // 农历
"extra_info": "元旦节" // 其它节气，一般为空
},
{
"date": "2026-01-02",
"type": 2,
"is_holiday": 1,
"name": "元旦节（休）",
"wage": 1,
"after": null,
"week": 5,
"target": "元旦节",
"lunar": "冬月十四",
"extra_info": ""
},
{
"date": "2026-01-03",
"type": 2,
"is_holiday": 1,
"name": "元旦节（休）",
"wage": 1,
"after": null,
"week": 6,
"target": "元旦节",
"lunar": "冬月十五",
"extra_info": ""
},
{
"date": "2026-01-04",
"type": 4,
"is_holiday": 0,
"name": "元旦节（班）",
"wage": 1,
"after": 1,
"week": 7,
"target": "元旦节",
"lunar": "冬月十六",
"extra_info": ""
}
]
}示例：
https://holiday.ailcc.com/api/holiday/allyear/
https://holiday.ailcc.com/api/holiday/allyear/2026
赞助本站—
长期维护一个网站的服务，对个人开发者来说，除掉运营费用，最难的就是耐心和坚持，(￣ー￣)。
本站该服务长期维护，并免费提供给大家使用。如果你觉得用的好，有钱的捧个钱场，没钱的捧个人场，尽量别大量无意义的调用就行了。
如果该服务对你有用，并打算长期使用，你可以赞助个1块、2、3的，当然10块也可以，但不要超过10块，有这钱自己留着买好吃的吧。
所有赞助的资金将用于该服务的服务器、流量、带宽、域名方面。
付款支持支付宝、微信，扫下方二维码，付款时请一定确认账号，赞助的金额无论大小，一律不退。
有任何问题，请第一时间截图并发邮件给站长：jack.liu@ailcc.com
