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

使用须知

1、这是由本人用业余时间开发的基于ThinkPHP 8的中国法定节假日API，免费提供给同样需要的人。
2、节假日信息我会尽快更新，如果发现某个节假日配置错误或没有配置，请联系我的QQ或留言反馈。
3、有其它需求也可以联系我，付费定制，预付款70%，价格可商议。
4、网站永久维护更新，放心使用，但请别乱用，带宽有限，请谅解。

联系方式

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

近期更新 2025-11-23 17:49:41

1、本次更新新增 标准 ICS 日历订阅接口，支持 Apple 全平台（iPhone、iPad、Mac）的原生日历订阅。
2、用户只需订阅一次，后续节假日更新将自动同步，无需重新添加。
3、新增 ICS 订阅接口： GET /api/holiday/ics<
4、支持自动更新： Apple 设备会按系统策略自动拉取最新节假日数据。
5、ICS 缓存优化： 通过 ETag 和 Last-Modified 提升性能，减少服务器压力。
6、苹果特有的日历颜色： 使用 X-APPLE-CALENDAR-COLOR 设置红色主题。
7、日历内容： 仅输出节日（type=2）、调休放假（type=3）、补班（type=4）。不输出普通工作日。

常见问题

1、节假日 api 现已支持 HTTPS 调用，不支持HTTP调用，必须是HTTPS。
2、网站使用白名单加访问IP进行访问限制，域名或IP未在白名单中的，接口每分钟仅允许查询31次，24小时最多可查询14400次（所有接口的总计查询次数）。
3、注册用户或白名单域名、IP不受访问次数的限制。

限额说明及规则

1、以下限额都是按照每个用户的域名或IP统计的，注册用户最多允许2个域名。
2、免费用户所有接口限额时间为 24 小时，每天凌晨00:01重置状态。
3、免费用户节假日 API 接口24小时内总计限额为 14400次/IP，每分钟限制31次。
4、如果限额太少不够用，可以发邮件说明情况，确定如为合理需求，可以提高额度。
5、免费用户限额目的是为了大家都能平均分配，保证访问速度。
6、免费用户限额的对象是针对IP，并不是所有用户共享。
7、免费用户如果是小区共享同一出口宽带，则可能会和其它人共享限额。
8、免费用户如果达到限制，可以手动重启自家光猫，重启后会变更公网IP，侧可享受新一轮的14400次查询（一般不建议，出现任何问题与本站无关）。

API接口说明文档

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

苹果官方已有中国法定节假日订阅，非必要不建议订阅本站日历，因为本站日历中包含24节气、其它节气及民俗节日等信息。

接口地址： GET https://holiday.ailcc.com/api/holiday/ics

接口功能：返回一个可供苹果日历、Google 日历、Outlook 等日历软件订阅的 ICS（iCalendar）日历文件，其中包含 “法定节假日、调休放假、补班” 的日期信息。

使用办法：该接口不需要任何参数，直接 GET 即可。

日历说明：服务器会自动返回当前年份 + 下一年份的节假日 ICS 内容。

日历更新：日历数据每次访问均为最新版本，用于保证订阅端能够自动更新。

接口包含：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: 指定日期的字符串，格式 ‘2018-02-23’。可以省略，则默认服务器的当前时间。

@return json: 如果不是节假日或周末，holiday字段为null。

{
  "code": 0,                    // 0服务正常。-1服务出错
  "type": { 
    "type": enum(0, 1, 2, 3，4),  // 节假日类型，分别表示 工作日、周末、节日、调休放假、补班。
    "name": "国庆节（休）",       // 节假日类型中文名，可能值为 周一 至 周日、假期的名字、某某调休。
    "week": 3                   // 一周中的第几天。值为 1 - 7，分别表示 周一 至 周日。
  },
  "holiday": {
    "holiday": true,            // true表示是节假日，false表示是调休。
    "name": "国庆节（休）",       // 节假日的中文名。如果是调休，则是调休的中文名，例如“国庆节（休）”。
    "wage": 3,                  // 薪资倍数，1表示是1倍工资，该数据不再详细维护。
    "date": "2025-10-01",       // 查询的时间参数。
    "after": null,              // 只在调休或补班下有该字段。1表示假后调休或补班，0表示假前调休或补班，否则为null。
    "target": "国庆节",          // 只在调休下有该字段。表示调休的节假日，否则为null。
    "rest": 39
  }
}

示例：

https://holiday.ailcc.com/api/holiday/info/2025-10-01
https://holiday.ailcc.com/api/holiday/info/2025-10-1

批量查询指定日期节假日信息 - 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,
      "name": "国庆节（休）",
      "wage": 1,
      "date": "2025-10-08",
      "rest": 32
    }
  },
  "type": {                         // 只有明确指定参数 type=Y 时才返回类型信息
    "2025-09-29": {                 // 一一对应holiday对象的key，holiday有多少个这里就有多少个
      "type": enum(0, 1, 2, 3，4),  // 节假日类型，分别表示 工作日、周末、节日、调休放假、补班。
      "name": "周一",               // 节假日类型中文名，可能值为 周一 至 周日、假期的名字、某某调休。
      "week": 1                     // 一周中的第几天。值为 1 - 7，分别表示 周一 至 周日。
    },
    "2025-10-08": {
      "type": 2,
      "name": "国庆节（休）",
      "week": 3
    }
  }
}

示例：

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",               // 节假日的日期。
    "rest": 4                           // 表示当前时间距离目标还有多少天。比如今天是 2018-09-28，距离 2018-10-01 还有3天。
  },
  "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，分别表示 周一 至 周日。
    },
    "workday": {                        // 对应 workday 中的日期类型，只有返回 workday 信息时才存在此日期类型
      "type": enum(0, 1, 2, 3，4),      // 节假日类型，分别表示 工作日、周末、节日、调休放假、补班。
      "name": "国庆节前补班",           // 节假日类型中文名，可能值为 周一 至 周日、假期的名字、某某调休。
      "week": 7                         // 一周中的第几天。值为 1 - 7，分别表示 周一 至 周日。
    }
  }
}

示例：

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/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                           // 同上。表示当前时间距离目标还有多少天。
  }
}

示例：

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",                 // 节假日的日期
      "rest": 39
    },
    "10-02": {
      "holiday": true,
      "name": "国庆节（休）",
      "wage": 3,
      "date": "2025-10-02",
      "rest": 38
    }
  }
  "type": {                                 // 只有明确指定参数 type=Y 时才返回类型信息
    "2025-10-01": {                         // 一一对应holiday对象的key，holiday有多少个这里就有多少个
      "type": enum(0, 1, 2, 3，4),          // 节假日类型，分别表示 工作日、周末、节日、调休放假、补班。
      "name": "国庆节（休）",               // 节假日类型中文名，可能值为 周一 至 周日、假期的名字、某某调休。
      "week": enum(1 - 7)                   // 一周中的第几天。值为 1 - 7，分别表示 周一 至 周日。
    },
    "2025-10-02": {
      "type": 2,
      "name": "国庆节（休）",
      "week": 4
    },
    "2025-10-03": {
      "type": 2,
      "name": "国庆节（休）",
      "week": 5
    },
  }
}

示例：

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

历史更新

增加农历及总体架构更新（重大改进）。 2025-11-22 23:25:37

1、增加全年农历功能
2、每分钟访问量增加至31次，一次性请求整月数据，但24小时内最多能请求14400次。
2、统一整个系统的节假日基础数据结构，所有 API 保证一致性。
4、统一 rest 计算逻辑，始终以服务器当前日期计算，完全统一。
5、统一日期输入规则，所有 API 增加日期校验。
6、统一 Redis 限流（全局限流）。
7、所有 API 结构统一并优化查询逻辑。
8、API 行为和返回结构完全统一。

更新2026年日历 2025-11-08 11:33:04

1、更新2026年日历。
2、修复并补全2025年日历。

修复功能性问题 2025-10-15 15:55:41

1、修复year接口查询问题。
2、修复info日期不完整时的查询问题。
3、修复权限管控的问题。

网站创建成功！ 2025-09-12 18:11:19

1、网站初建成功。
2、增加各类接口。
3、增加权限控制。
4、增加接口管控及日志。