# 节假日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

# Holiday API (China)

A lightweight, free and open-source Chinese public holiday API. It supports offline usage and can be easily integrated into any PHP project.

## Features

- Covers statutory public holidays from 2019 to 2026
- Dual usage modes: HTTP endpoint (online) and PHP SDK (offline)
- JSONP callback support for cross-origin requests
- Two response modes: wage multiplier mode and detailed type mode
- Automatic detection of weekends, compensatory workdays, and public holidays
- Static cache plus local file cache for stable performance
- Automatically fetches missing year data from the remote repository

## Directory Structure

```
holidays_api/
├── index.php                # HTTP entry point (online endpoint)
├── include/
│   └── dateapi.class.php    # Core DateApi class
├── data/                    # Yearly holiday 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
```

## HTTP Endpoint Usage

After deploying to a PHP-enabled server, call it via 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 callback
```

### Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `d` | Yes | Date in `20250101` or `2025-01-01` format |
| `type` | No | Response mode, default `1`. `1` = wage multiplier mode, `2` = detailed type mode |
| `callback` | No | JSONP callback name for cross-origin scenarios |

### Response Format (type=1 — Wage Multiplier)

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

- `0`: Workday (no extra pay)
- `1`: Weekend (double pay)
- `2`: Statutory public holiday (triple pay)

### Response Format (type=2 — Detailed Type)

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

- `1`: Workday
- `2`: Compensatory workday (treated as workday)
- `3`: Weekend
- `4`: Statutory public holiday

### Error Responses

```json
{"status": 0, "info": "Invalid date format"}
{"status": 0, "info": "Failed to retrieve data"}
```

## Offline SDK Usage

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

$api = new DateApi();

// Option 1: wage multiplier (0 / 1 / 2)
$result = $api->getday('2025-01-01');

// Option 2: detailed type (1 / 2 / 3 / 4)
$result = $api->getday('2025-01-01', 2);
```

## Data Format

Each JSON file under the `data/` directory stores one year's holiday data. Keys are in `MMDD` format and values are type codes:

| Value | Meaning |
|-------|---------|
| `0` | Compensatory workday (rest day moved to workday) |
| `1` | Statutory holiday (treated as workday) |
| `2` | Statutory holiday (rest day) |

Example from `2025_data.json`:

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

Dates not listed in the file are automatically determined by the actual weekend rule.

## Online Demos

- Free API: http://tool.bitefu.net/jiari/
- VIP Channel: http://tool.bitefu.net/jiari/vip.php
- VIP Dedicated: http://vip.bitefu.net/jiari/

## Development Notes

- The original Baidu APIStore holiday API was also provided by the same author, later made independent due to platform restrictions.
- The open-source version provides the core offline query capability, feel free to customize it.
- For technical consulting or custom development, please contact the author: (rar3@sina.com,xiaogg@sina.cn)

#### Donate to me


<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>
## Multi-language Examples

For complete sample code to call this API from various programming languages (cURL, JavaScript / jQuery / Node.js, Python, Java, C#, Go, Ruby, PHP, Swift, Kotlin, WeChat Mini Program, uni-app, Flutter, etc.), please see:

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

## License

This project is released under the license declared in the [LICENSE](./LICENSE) file.