中国节假日查询

接口标识: holiday 价格: 0.005 元/次同步响应

接口介绍
接口文档
在线测试

接口简介

中国节假日查询接口按法定节假日与调休安排提供四种查询：判断当天或指定日期是否放假、是否上班并区分日期类型（法定假日/周末/调休上班日/工作日），拉取某一年全部放假日清单与总天数，预测下一个法定节假日的名称、日期与倒计时天数。调休补班的周六周日正确判定为工作日，覆盖 2004~2027 年。适合考勤打卡、排班调度、电商营销日历与物流时效估算场景。

详细介绍

![中国节假日查询接口封面](https://fujian.phpwc.com/pyapi/uploads/site/20261111/apiops_holiday__1794363299_f5571b28ad34.png)

今天放不放假？这周六要不要补班？下一个假期还有几天？传入日期就能拿到法定节假日安排的准确答案。

## 接口概述
面向考勤、排班、营销日历等需要准确判断「哪天放假、哪天上班」的场景，接口按中国法定节假日与调休安排提供四种查询：判断当天或指定日期的放假与上班状态、拉取全年放假日清单、预测下一个法定节假日。日期类型自动区分法定假日、周末、调休上班日与普通工作日，周末补班的日子会被正确判定为工作日，覆盖 2004 至 2027 年，结果同步返回，可直接嵌入 OA 系统、电商大促日历与物流时效估算逻辑。

## 核心能力
1. **单日判断**：查询任意日期是否放假、是否上班，以及所属假日名称。
2. **四类日期**：自动区分法定假日、周末、调休上班日与普通工作日，补班日不误判。
3. **全年清单**：一次拿到某一年全部放假日与假期总天数，假日均带名称。
4. **假期预测**：查询指定日期之后最近的法定节假日名称、日期与倒计时天数。

## 产品优势
1. **口径规范**：严格按法定节假日与调休安排判定，补班、连休都能正确区分。
2. **接入简单**：四种查询共用一个入口，POST 同步返回。
3. **覆盖广泛**：支持 2004 至 2027 年，历史复盘与未来排期都能查。
4. **字段即用**：日期类型、假日名称、倒计时天数结构化返回，无需二次加工。
5. **降本增效**：考勤、排班、营销日历共用一套节假日数据，免去每年手工维护假日表。

## 效果展示
一句话理解：它就像一本翻熟了的放假安排台历——随便指一天，它告诉你是放假、上班，还是补班的周末。

以一次真实调用为例，你要传的参数：

| 参数 | 本次示例值 | 说明 |
|------|-----------|------|
| action | detail | 查询类型：today 当天 / detail 指定日 / year 全年 / next 下个假期，默认 today |
| date | 2026-10-01 | 公历日期 YYYY-MM-DD，today/detail/next 使用，缺省为当天 |

你会拿到的结果：

| 返回内容 | 本次示例值 | 对应字段 |
|---------|-----------|---------|
| 查询日期 | `"2026-10-01"` | `date` |
| 是否放假 | true | `is_holiday` |
| 假日名称 | `"国庆节"` | `holiday_name`，非法定假日为空串 |
| 是否工作日 | false | `is_workday` |
| 日期类型 | `"法定假日"` | `date_type`，四类：法定假日/周末/调休上班日/工作日 |

API请求示例：

```
POST /api/holiday
action=detail&date=2026-10-01
```

API响应示例：

```json
{
  "code": 0,
  "desc": "成功",
  "data": {
    "date": "2026-10-01",
    "is_holiday": true,
    "holiday_name": "国庆节",
    "is_workday": false,
    "date_type": "法定假日"
  },
  "request_id": "f0b2c4d6e8a143579d1f3b5c7e9a0d2f"
}
```

detail 与 today 返回结构相同；year 操作返回 year、holiday_count 与 holidays 列表，next 操作返回 next_holiday_name、next_holiday_date 与 next_holiday_days。

## 应用场景
- **考勤排班**：自动判断当天是否需要打卡上班，补班日不再误判。
- **营销日历**：电商大促与内容运营围绕法定假期提前排期。
- **物流时效**：结合放假安排估算发货与送达时间承诺。
- **倒计时工具**：应用内展示距下一个法定节假日的天数。

## 应用案例
**HR 系统开发者**：考勤系统必须准确区分法定假日、周末与调休补班日，此前每年手工维护假日表，费时且容易出错。接入本接口后，查一个日期即知是否放假与日期类型，全年清单还能一次生成排班基础数据，假日表维护工作彻底取消。

**电商运营**：大促节奏要围绕法定假期安排，运营团队用 year 查询提前拿到全年放假表规划活动档期，用 next 查询在首页做「假期倒计时」氛围栏目，排期会与活动上线不再依赖人工翻日历。

常见问题

Q：支持哪些年份？

A：2004 至 2027 年，日期或年份超出范围返回参数错误；next 查询在临近数据边界时若找不到假期会返回说明提示。

Q：调休上班的周六周日算什么？

A：算工作日：is_workday=true，date_type 为「调休上班日」，考勤逻辑可放心按 is_workday 判断。

Q：next 查询会返回普通周末吗？

A：不会。next 只返回带名称的法定节假日（如国庆节、中秋节），忽略普通周末，并给出假期日期与倒计时天数。

节假日放假安排调休日历

接口地址： https://www.phpwc.cn/api/holiday

请求方式： POST

业务请求参数

参数名	类型	必填	默认值	说明
`action`	string	选填	`today`	操作：today 当日/detail 指定日/year 年度列表/next 下个假期
`date`	string	选填	-	公历日期 YYYY-MM-DD，today/detail/next 使用，缺省为当天
`year`	int	选填	-	年份 2004-2027，year 操作必填

查看签名算法查看调用示例

响应参数

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	业务数据（成功时返回）
`date`	string	查询日期
`is_holiday`	boolean	是否放假
`holiday_name`	string	假日名称（法定假日才有）
`is_workday`	boolean	是否工作日（含调休上班日）
`date_type`	string	日期类型：法定假日/周末/调休上班日/工作日
`year`	int	年份（year 操作）
`holiday_count`	int	该年假期总天数（year 操作）
`holidays`−	array	该年放假安排数组（year 操作）
`date`	string	放假日期
`holiday_name`	string	假日名称
`is_workday`	boolean	是否工作日
`next_holiday_name`	string	下一个假期名称
`next_holiday_date`	string	下一个假期日期
`next_holiday_days`	int	距下一个假期天数
`request_id`	string	请求追踪ID

JSON 示例：

调用成功：

{
  "code": 0,
  "desc": "success",
  "data": { ... },
  "request_id": "abc123..."
}

调用失败：

{
  "code": 999,
  "desc": "错误描述",
  "request_id": "abc123..."
}

请先登录后使用在线测试