# 节假日api

**Repository Path**: web/holidays_api

## Basic Information

- **Project Name**: 节假日api
- **Description**: 免费节假日API 开源了,可以离线调用, 可以集成到自己系统中
- **Primary Language**: PHP
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 280
- **Forks**: 80
- **Created**: 2019-02-28
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: utils

**Tags**: None

## README

# 节假日 API

精简、免费、开源的中国节假日 API，支持离线调用，可集成到任意 PHP 项目中。

## 功能特性

- 支持 `2019` 至 `2026` 年法定节假日数据
- 在线接口调用（GET 传参）及离线 SDK 调用两种方式
- 支持 JSONP 跨域回调
- 提供两种返回模式：工资倍数模式、详细类型模式
- 自动识别周末 / 调休 / 法定节假日
- 静态缓存 + 本地文件缓存，性能稳定
- 缺失年份数据时自动从远程仓库回源下载

## 目录结构

```
holidays_api/
├── index.php                # HTTP 入口文件（在线接口）
├── include/
│   └── dateapi.class.php    # 核心日期 API 类
├── data/                    # 各年份节假日数据（JSON）
│   ├── 2019_data.json
│   ├── 2020_data.json
│   ├── 2021_data.json
│   ├── 2022_data.json
│   ├── 2023_data.json
│   ├── 2024_data.json
│   ├── 2025_data.json
│   └── 2026_data.json
├── README.md
└── README.en.md
```
测试APIKEY获取（关注公众号回复：节假日）

![关注公众号回复：节假日](https://gitee.com/web/holidays_vip_api/raw/master/images/qrcode.jpg "关注公众号回复：节假日")


## 在线接口使用

部署到支持 PHP 的服务器后，直接通过 HTTP GET 调用：

```
GET /index.php?d=2025-01-01
GET /index.php?d=20250101
GET /index.php?d=2025-01-01&type=2
GET /index.php?d=2025-01-01&callback=myFn   # JSONP 回调
```

### 参数说明

| 参数 | 必填 | 说明 |
|------|------|------|
| `d` | 是 | 日期，支持 `20250101` 或 `2025-01-01` 格式 |
| `type` | 否 | 返回类型，默认 `1`。`1`=工资倍数模式，`2`=详细类型模式 |
| `callback` | 否 | JSONP 回调函数名，用于跨域场景 |

### 返回格式（type=1 工资倍数）

```json
{
  "status": 1,
  "info": 2
}
```

- `0`：工作日（正常工资）
- `1`：周末（双倍工资）
- `2`：法定节假日（三倍工资）

### 返回格式（type=2 详细类型）

```json
{
  "status": 1,
  "info": 4
}
```

- `1`：工作日
- `2`：调休（按工作日处理）
- `3`：周末
- `4`：法定节假日

### 返回错误

```json
{"status": 0, "info": "日期格式错误"}
{"status": 0, "info": "数据获取失败"}
```

## 离线 SDK 调用

```php
include('include/dateapi.class.php');

$api = new DateApi();

// 方式一：工资倍数（0/1/2）
$result = $api->getday('2025-01-01');

// 方式二：详细类型（1/2/3/4）
$result = $api->getday('2025-01-01', 2);
```

## 数据格式

`data/` 目录下每个 JSON 文件存放一年的节假日数据，键为 `MMDD`，值为类型编码：

| 取值 | 含义 |
|------|------|
| `0` | 调休（休息日调为工作日） |
| `1` | 法定节假日（按工作日处理） |
| `2` | 法定节假日（休息日） |

例如 `2025_data.json`：

```json
{
  "0101": 2,
  "0208": 0,
  "0501": 2,
  "1001": 2
}
```

未在表中的日期将根据实际周末规则自动判定。

## 在线 Demo

- 在线接口：http://tool.bitefu.net/jiari/
- 开源接口：https://tool.bitefu.net/jiari/openapi.php
- VIP 通道：http://tool.bitefu.net/jiari/vip.php
- VIP 专用通道：http://vip.bitefu.net/jiari/

## 开发说明

- 原百度 APIStore 节假日接口即为作者本人提供，后因平台限制独立开源
- 开源版本提供最核心的离线查询能力，可自行二次开发
- 如需技术指导或定制开发，可联系作者（rar3@sina.com,xiaogg@sina.cn）

## 捐助我


<a href="http://tool.bitefu.net/pay/alipayred.jpg" target="_blank"><img height="300" src="https://oscimg.oschina.net/oscnet/69e93259cb3fa4f12a2c4e96dfc65984fb9.jpg" width="200" /></a> <a href="http://tool.bitefu.net/pay/wxpay.png" target="_blank"><img height="274" src="https://oscimg.oschina.net/oscnet/1118495c283edf13318ed999c1ad23c1614.jpg" width="200" /></a> <a href="http://tool.bitefu.net/pay/alipay.jpg" target="_blank"><img height="272" src="https://oscimg.oschina.net/oscnet/1adfcc1bdf40d6cf35bcc80f94678d52e98.jpg" width="200" /></a>

## 多语言调用示例

各主流编程语言（cURL、JavaScript / jQuery / Node.js、Python、Java、C#、Go、Ruby、PHP、Swift、Kotlin、微信小程序、uni-app、Flutter 等）调用本 API 的完整示例代码，请查阅：

👉 [examples.md](./examples.md)

## 许可协议

本项目基于 [LICENSE](./LICENSE) 文件中声明的开源协议发布。