API 使用手册 - 免费节假日 API

使用须知

1、禁止任何违反国家法律、法规的站点调用本站接口。
2、建议在调用本站API时，使用本地缓存 + 兜底逻辑，才是必须的最佳实践，既能避免高频调用触发本站限流，也能在网站临时不可用时保障业务正常运行。
3、这是用业余时间开发的基于ThinkPHP 8的中国法定节假日API，免费提供给需要的个人开发者。
4、节假日信息会尽快更新，如发现某个节假日配置错误或没有配置，请联系QQ或发送邮件反馈。
5、系统会对异常频率请求、无效高并发调用、恶意刷接口等行为进行监控，自然日内429返回超300进行24小时封禁，自然日内423返回超200永久封禁，恶意请求访问的 IP，将被永久封禁。
6、已永久封禁IPv4列表：210.21.237.170，14.212.104.70，39.150.193.166，1.192.178.202
7、已永久封禁IPv6列表：240e:306:32c5:7101:c5b2:63fd:2453:42f1

联系方式

QQ：66257875
邮箱：Jack.Liu@ailcc.com (PS：邮箱联系更快)

近期更新 -- 修复已知问题！ 2026-07-14 23:03:38

1、修复已知问题。
2、重构用户注册流程与后台配置优化。
3、用户体验与性能优化，升级验证界面，优化交互体验，明确权限边界。
4、架构与性能改进，滑块验证组件重构与逻辑拆分，接口标准化，安全性加固。
5、行为审计日志系统更新，实现全站行为轨迹记录，异步日志数据发送及存储。
6、支持用户端通过日志查看操作轨迹，实现操作逻辑的 100% 可追溯。

常见问题

1、节假日 api 不支持HTTP调用，必须是HTTPS。
2、网站使用白名单加访问IP进行访问限制，域名、IP未在白名单中的，接口每分钟仅允许查询31次，24小时最多可查询10000次（所有接口的总计查询次数）。
3、注册白名单用户或更高级用户，拥有更多的访问次数。
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小时内总计限额为 10000次/IP，每分钟限制31次。

API接口说明文档

苹果设备订阅法定节假日 - ICS

苹果官方已有中国法定节假日订阅，非必要不建议订阅本站日历，因为本站日历中包含24节气、其它节气及民俗节日等信息。
个人日历功能因考虑到垃圾日历、广告网址等问题，停止注册使用，后续只允许邀请用户及付费用户使用。也只可以只订阅本站默认的万年历，该订阅无需注册即可订阅。

接口地址： GET https://holiday.ailcc.com/api/holiday/ics
接口功能：返回一个可供苹果日历、Google 日历、Outlook 等日历软件订阅的 ICS（iCalendar）日历文件，其中包含 “法定节假日、调休放假、补班” 的日期信息。
使用办法：该接口不需要任何参数，直接在设备上的日历中订阅即可。
日历说明：服务器会自动返回“前两年 + 当前年份 + 后两年”的节假日 ICS 内容，只更新近5年的日历，法定节假日随国务院通知更新。例如当前年份为 2026 年，则日历范围为 2024-01-01 至 2028-12-31，若最后一年无节假日或日历内容，通常表示该年度官方数据尚未发布或站长尚未维护。
日历更新：日历数据每次访问均为最新版本，用于保证订阅端能够自动更新。
接口包含：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 lang: 是否返回节假日的英文名称，默认不返回。可选值：’en’ 返回。
@return json: 如果不是节假日或周末，holiday字段为null。

{
  "code": 0,                                    // 0服务正常。-1服务出错
  "type": { 
    "type": enum(0, 1, 2, 3，4),                // 节假日类型，分别表示 工作日、周末、节日、调休放假、补班。
    "name": "国庆节（休）",                     // 节假日类型中文名，可能值为 周一 至 周日、假期的名字、某某调休。
    "week": 3                                   // 一周中的第几天。值为 1 - 7，分别表示 周一 至 周日。
    "cnLunar": "八月初十",                      // 农历
    "extra_info": "国庆节",                     // 其它节气
    "name_en": "National Day of China",         // name字段的节假日英文名称
    "extra_en": "National Day of China"         // 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                                  // 表示当前时间距离目标还有多少天。
    "name_en": "National Day of China"          // name字段的节假日英文名称
  }
}

示例：

https://holiday.ailcc.com/api/holiday/info/2025-10-1
https://holiday.ailcc.com/api/holiday/info/2025-10-01
https://holiday.ailcc.com/api/holiday/info/2025-10-01?lang=en

批量查询指定日期节假日信息 - batch

接口地址：GET https://holiday.ailcc.com/api/holiday/batch?d=$date&type=Y
@params d: 指定日期的字符串，多个日期之间使用且只能使用英文逗号“,”连接。最大长度查询个数31，多余日期不返回，格式 ‘2025-10-01’。
@params type: 是否返回日期类型，默认不返回。可选值：’Y’ 返回，’N’ 不返回。
@params lang: 是否返回节假日的英文名称，默认不返回。可选值：’en’ 返回。
@return json: 返回以日期为key的对象。

{
  "code": 0,                                // 0服务正常。-1服务出错
  "holiday": {                              // 传过来的日期是什么，key就是什么。传多少个就有多少个。
    "2025-09-9": null,                      // 如果不是节假日，则为null
    "2025-10-08": {                         // holiday的值都是一致的
      "holiday": true,                      // true表示是节假日，false表示是调休。
      "name": "国庆节（休）",               // 节假日的中文名。如果是调休，则是调休的中文名，例如“国庆节（休）”。
      "wage": 1,                            // 薪资倍数，1表示是1倍工资，该数据不再详细维护。
      "date": "2025-10-08",                 // 查询的时间参数。
      "rest": 1,                            // 表示当前时间距离目标还有多少天。
      "name_en": "National Day of China"    // name字段的英文名称
    }
  },
  "type": {                                 // 只有明确指定参数 type=Y 时才返回类型信息
    "2025-09-9": {                          // 一一对应holiday对象的key，holiday有多少个这里就有多少个
      "type": enum(0, 1, 2, 3，4),          // 节假日类型，分别表示 工作日、周末、节日、调休放假、补班。
      "name": "周二",                       // 节假日类型中文名，可能值为 周一 至 周日、假期的名字、某某调休。
      "week": 1                             // 一周中的第几天。值为 1 - 7，分别表示 周一 至 周日。
      "cnLunar": "七月十八",                // 农历
      "extra_info": "",                     // 其它节气，一般为空
      "name_en": "Tuesday"                  // name字段的英文名称
    },
    "2025-10-08": {
      "type": 2,
      "name": "国庆节（休）",
      "week": 3
      "cnLunar": "八月十七",
      "extra_info": "寒露",
      "name_en": "National Day of China",   // name字段的英文名称
      "extra_en": "Cold Dew"                // 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
https://holiday.ailcc.com/api/holiday/batch?d=2025-9-9,2025-10-08,2025-03-1&type=Y&lang=en

获取指定日期的下一个节假日（如果在放假前有调休，也会返回）- next

接口地址：GET https://holiday.ailcc.com/api/holiday/next/$date?type=Y&week=Y
@params $date: 指定日期的字符串，格式“2025-09-27”，日期可以省略，则默认服务器的当前时间。
@params type: 是否返回日期类型，默认不返回。可选值：’Y’ 返回，’N’ 不返回。
@params week: 节假日是否包含周末，默认不包含。可选值：’Y’ 包含周末，’N’ 不包含。
@params lang: 是否返回节假日的英文名称，默认不返回。可选值：’en’ 返回。
@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,                              // 表示当前时间距离目标还有多少天。
    "name_en": "National Day of China"      // name字段的英文名称
  },
  "workday": {                              // 如果节假日前没调休，则此字段为null。
    "holiday": false,                       // 此字段一定为false。
    "name": "国庆节（班）",                 // 调休的中文名。
    "after": null,                          // 只在调休或补班下有该字段，1表示假后调休或补班，0表示假前调休或补班，否则为null。
    "wage": 1,                              // 薪资倍数，3表示是3倍工资，该字段不在详细维护。
    "target": "国庆节",                     // 表示调休的节假日。
    "date": "2025-09-28",                   // 表示要调休的日期。
    "rest": 1,                              // 表示当前时间距离目标还有多少天。
    "name_en": "National Day of China"      // name字段的英文名称
  },
  "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",                 // 当天时间
      "name_en": "National Day of China"    // name字段的英文名称
    },
    "workday": {                            // 对应 workday 中的日期类型，只有返回 workday 信息时才存在此日期类型
      "type": enum(0, 1, 2, 3，4),          // 节假日类型，分别表示 工作日、周末、节日、调休放假、补班。
      "name": "国庆节（班）",               // 节假日类型中文名，可能值为 周一 至 周日、假期的名字、某某调休。
      "week": 7                             // 一周中的第几天。值为 1 - 7，分别表示 周一 至 周日。
      "cnLunar": "八月初七",                // 农历
      "extra_info": "",                     // 其它节气，一般为空
      "date": "2025-09-28",                 // 当天时间
      "name_en": "National Day of China"    // name字段的英文名称
    }
  }
}

示例：

https://holiday.ailcc.com/api/holiday/next/
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/2025-09-27?type=Y&week=Y&lang=en

获取指定日期的下一个工作日（工作日包含正常工作日、调休）不包含当天 - nextWorkday

接口地址：GET https://holiday.ailcc.com/api/holiday/nextWorkday/$date
@params $data:指定日期的字符串，格式“2025-10-01”，时间可以省略，则默认服务器的当前时间。
@params lang: 是否返回节假日的英文名称，默认不返回。可选值：’en’ 返回。
@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": "",                       // 其它节气，一般为空
    "name_en": "Thursday"                   // name字段英文名称
  }
}

示例：

https://holiday.ailcc.com/api/holiday/nextWorkday/
https://holiday.ailcc.com/api/holiday/nextWorkday/2025-10-1
https://holiday.ailcc.com/api/holiday/nextWorkday/2025-10-01
https://holiday.ailcc.com/api/holiday/nextWorkday/2025-10-01?lang=en

获取指定年份或年月份的所有节假日信息 - year

接口地址：GET https://holiday.ailcc.com/api/holiday/year/$date
@params $date:指定年份或年月份，格式“2025-10”，“2025-9” 或者“2025”。可以省略，则默认服务器当前时间的年份。
@params type:是否返回日期类型，默认不返回。可选值：’Y’ 返回，’N’ 不返回。
@params week:节假日是否包含周末，默认不包含。可选值：’Y’ 包含周末，’N’ 不包含。
@params lang: 是否返回节假日的英文名称，默认不返回。可选值：’en’ 返回。
@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,                           // 表示当前时间距离目标还有多少天。
      "name_en": "National Day of China",   // name字段英文名称
      "extra_en": "National Day of China"   // extra_info字段英文名称
    },
    "10-02": {
      "holiday": true,
      "name": "国庆节（休）",
      "wage": 3,
      "date": "2025-10-02",
      "cnLunar": "八月十一",
      "extra_info": "",
      "rest": 40,
      "name_en": "National Day of China"
    }
  }
  "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": "国庆节",               // 其它节气，一般为空
      "name_en": "National Day of China",   // name字段英文名称
      "extra_en": "National Day of China"   // extra_info字段英文名称
    },
    "2025-10-02": {
      "type": 2,
      "name": "国庆节（休）",
      "week": 4
      "cnLunar": "八月十一",
      "extra_info": "",
      "name_en": "National Day of China"
    },
    "2025-10-03": {
      "type": 2,
      "name": "国庆节（休）",
      "week": 5
      "cnLunar": "八月十二",
      "extra_info": "",
      "name_en": "National Day of China"
    },
  }
}

示例：

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
https://holiday.ailcc.com/api/holiday/year/2025-10?type=Y&week=Y&lang=en

获取指定年份里每天的信息 - allyear

接口地址：GET https://holiday.ailcc.com/api/holiday/allyear/$date
@params $date:指定年份2026”，可以省略，则默认服务器当前时间的年份。
@params lang: 是否返回节假日的英文名称，默认不返回。可选值：’en’ 返回。
@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": "元旦节",               // 其它节气，一般为空
      "name_en": "New Year's Day",          // name字段英文名称
      "extra_en": "New Year's Day"          // extra_info字段英文名称
    },
    {
      "date": "2026-01-02",
      "type": 2,
      "is_holiday": 1,
      "name": "元旦节（休）",
      "wage": 1,
      "after": null,
      "week": 5,
      "target": "元旦节",
      "lunar": "冬月十四",
      "extra_info": "",
      "name_en": "New Year's Day"
    },
    {
      "date": "2026-01-03",
      "type": 2,
      "is_holiday": 1,
      "name": "元旦节（休）",
      "wage": 1,
      "after": null,
      "week": 6,
      "target": "元旦节",
      "lunar": "冬月十五",
      "extra_info": "",
      "name_en": "New Year's Day"
    },
    {
      "date": "2026-01-04",
      "type": 4,
      "is_holiday": 0,
      "name": "元旦节（班）",
      "wage": 1,
      "after": 1,
      "week": 7,
      "target": "元旦节",
      "lunar": "冬月十六",
      "extra_info": "",
      "name_en": "New Year's Day"
    },
    {
      "date": "2026-01-05",
      "type": 0,
      "is_holiday": 0,
      "name": "周一",
      "wage": 1,
      "after": null,
      "week": 1,
      "target": "",
      "lunar": "冬月十七",
      "extra_info": "小寒",
      "name_en": "Monday",
      "extra_en": "Lesser Cold"
    },
  ]
}

示例：

https://holiday.ailcc.com/api/holiday/allyear/
https://holiday.ailcc.com/api/holiday/allyear/2026
https://holiday.ailcc.com/api/holiday/allyear/2026?lang=en

赞助本站—

长期维护一个网站的服务，对个人开发者来说，除掉运营费用，最难的就是耐心和坚持，(￣ー￣)。
本站该服务长期维护，并免费提供给大家使用。如果你觉得用的好，有钱的捧个钱场，没钱的捧个人场，尽量别大量无意义的调用就行了。
如果该服务对你有用，并打算长期使用，你可以赞助个1块、2、3的，当然10块也可以，但不要超过10块，有这钱自己留着买好吃的吧。
所有赞助的资金将用于该服务的服务器、流量、带宽、域名方面。
付款支持支付宝、微信，扫下方二维码，付款时请一定确认账号，赞助的金额无论大小，一律不退。
付款时请一定要写备注，或者你想对站长传达的话，谢谢。
有任何问题，请第一时间截图并发邮件给站长：jack.liu@ailcc.com

微信扫码随意赞助

感谢您对 Holiday 中国法定节假日API 的支持

赞助记录

赞助时间	赞助名称	赞助金额（元）	赞助方式	赞助备注
2026-07-23 22:11:34	*正	￥3.00	微信
2026-07-18 20:45:13	***年	￥1.00	微信
2026-07-12 17:31:44	*风	￥5.00	微信	感谢兄弟为爱发电，小小的支持不成敬意
2026-04-12 15:53:00	***东	￥3.00	支付宝
2026-03-23 15:28:38	***k	￥1.00	微信
2026-02-25 22:55:27	**林	￥0.50	支付宝
2026-02-02 10:32:11	***爱	￥1.00	微信
2026-01-22 09:19:01	*哦	￥3.00	微信

历史更新

查看完整历史更新

使用须知

联系方式

近期更新 -- 修复已知问题！ 2026-07-14 23:03:38

常见问题

限额说明及规则

API接口说明文档

苹果设备订阅法定节假日 - ICS

📱 订阅方式：

获取指定日期的节假日信息 - info

示例：

批量查询指定日期节假日信息 - batch

示例：

获取指定日期的下一个节假日（如果在放假前有调休，也会返回）- next

示例：

获取指定日期的下一个工作日（工作日包含正常工作日、调休）不包含当天 - nextWorkday

示例：

获取指定年份或年月份的所有节假日信息 - year

示例：

获取指定年份里每天的信息 - allyear

示例：

赞助本站—

微信扫码 随意赞助

支付宝扫码 随意赞助

赞助记录

历史更新

微信扫码 随意赞助

支付宝扫码 随意赞助

微信扫码随意赞助

支付宝扫码随意赞助

微信扫码随意赞助

支付宝扫码随意赞助