https://github.com/headwindz/public-holidays
public holidays open apis
https://github.com/headwindz/public-holidays
openapi public-holidays
Last synced: 2 months ago
JSON representation
public holidays open apis
- Host: GitHub
- URL: https://github.com/headwindz/public-holidays
- Owner: headwindz
- License: mit
- Created: 2025-12-26T12:34:01.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-24T10:05:04.000Z (5 months ago)
- Last Synced: 2026-01-24T20:05:19.669Z (5 months ago)
- Topics: openapi, public-holidays
- Language: TypeScript
- Homepage: https://public-holidays.toolhub.run/
- Size: 383 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Public holidays API
A comprehensive public holidays API providing holiday data for 60 countries and regions across multiple years (2020-2026). Built with Next.js and TypeScript.
🌐 **Doc**: [https://public-holidays.toolhub.run/](https://public-holidays.toolhub.run/)
## Features
- 🌍 **60 countries & regions** - Comprehensive coverage of public holidays worldwide
- 📅 **Multiple years** - Data available for 2020, 2021, 2022, 2023, 2024, 2025, and 2026
- 🚀 **Fast API** - Built on Next.js API routes for optimal performance
- 🎨 **Interactive documentation** - Built-in API tester and documentation
- 📱 **Responsive design** - Works seamlessly on all devices
## Supported countries
The API covers 60 countries and regions including:
- 🇨🇳 China (cn)
- 🇺🇸 United States (us)
- 🇬🇧 United Kingdom (uk)
- 🇨🇦 Canada (ca)
- 🇦🇺 Australia (au)
- 🇩🇪 Germany (de)
- 🇫🇷 France (fr)
- 🇯🇵 Japan (jp)
- 🇮🇳 India (in)
- 🇧🇷 Brazil (br)
- 🇲🇽 Mexico (mx)
- And 48 more...
See the [data directory](./data/2025) for the complete list of country codes.
## API usage
### Endpoint
```
GET https://public-holidays.toolhub.run/api/public-holidays?year={year}&code={code}
```
### Parameters
- `year` (required) - The year for which to retrieve holidays (e.g., 2020, 2021, 2022, 2023, 2024, 2025, 2026)
- `code` (required) - The ISO 3166-1 alpha-2 country/region code (e.g., cn, us, uk, ca)
### Example request
```bash
curl "https://public-holidays.toolhub.run/api/public-holidays?year=2025&code=cn"
```
### Example response
```json
{
"data": [
{
"localName": "元旦",
"name": "New Year's Day",
"code": "CN",
"fixed": true,
"global": true,
"counties": null,
"launchYear": null,
"types": ["Public"],
"startDate": "2025-01-01T00:00:00.000Z",
"endDate": "2025-01-01T23:59:59.999Z"
},
{
"localName": "春节",
"name": "Spring Festival (Chinese New Year)",
"code": "CN",
"fixed": false,
"global": true,
"counties": null,
"launchYear": null,
"types": ["Public"],
"startDate": "2025-01-28T00:00:00.000Z",
"endDate": "2025-02-04T23:59:59.999Z"
},
{
"localName": "清明节",
"name": "Tomb Sweeping Day (Qingming Festival)",
"code": "CN",
"fixed": false,
"global": true,
"counties": null,
"launchYear": null,
"types": ["Public"],
"startDate": "2025-04-04T00:00:00.000Z",
"endDate": "2025-04-06T23:59:59.999Z"
},
{
"localName": "劳动节",
"name": "Labor Day",
"code": "CN",
"fixed": true,
"global": true,
"counties": null,
"launchYear": null,
"types": ["Public"],
"startDate": "2025-05-01T00:00:00.000Z",
"endDate": "2025-05-05T23:59:59.999Z"
},
{
"localName": "端午节",
"name": "Dragon Boat Festival",
"code": "CN",
"fixed": false,
"global": true,
"counties": null,
"launchYear": null,
"types": ["Public"],
"startDate": "2025-05-31T00:00:00.000Z",
"endDate": "2025-06-02T23:59:59.999Z"
},
{
"localName": "国庆节 / 中秋节",
"name": "National Day & Mid-Autumn Festival",
"code": "CN",
"fixed": true,
"global": true,
"counties": null,
"launchYear": 1949,
"types": ["Public"],
"startDate": "2025-10-01T00:00:00.000Z",
"endDate": "2025-10-08T23:59:59.999Z"
}
]
}
```
### Error responses
**400 bad request** - Missing required parameters
```json
{
"error": "Both year and code parameters are required"
}
```
**404 not found** - Data not available for specified year/country
```json
{
"error": "Data not found for the specified year and country/region code"
}
```
## Getting started
### Prerequisites
- Node.js 18+
- pnpm (recommended) or npm
### Installation
1. Clone the repository:
```bash
git clone https://github.com/headwindz/public-holidays
cd public-holidays
```
2. Install dependencies:
```bash
pnpm install
```
3. Run the development server:
```bash
pnpm dev
```
4. Open [http://localhost:3000](http://localhost:3000) to view the application
### Build for production
```bash
pnpm build
pnpm start
```
## Project structure
```
public-holidays/
├── app/
│ ├── api/
│ │ └── public-holidays/
│ │ └── route.ts # API endpoint
│ ├── globals.css # Global styles
│ ├── layout.tsx # Root layout
│ └── page.tsx # Landing page
├── data/
│ ├── 2020/ # 2020 holiday data
│ ├── 2021/ # 2021 holiday data
│ ├── 2022/ # 2022 holiday data
│ ├── 2023/ # 2023 holiday data
│ ├── 2024/ # 2024 holiday data
│ └── 2025/ # 2025 holiday data
│ ├── cn/
│ │ └── index.json
│ ├── us/
│ │ └── index.json
│ └── ... # 60 countries total
└── package.json
```
## Technology stack
- **Framework**: [Next.js 15](https://nextjs.org) with App Router
- **Language**: TypeScript
- **Styling**: Tailwind CSS
- **Package manager**: pnpm
## Data sources
Holiday data is generated by AI and includes:
- Fixed national holidays
- Movable holidays (Easter, Lunar New Year, Ramadan, etc.)
- Holiday durations
- Bank holidays
**Note**: While the data is generated with care, please verify critical dates with official government sources for production use. If you find any discrepancies, feel free to open an issue.
## Contributing
Contributions are welcome! Please feel free to submit a [Issue](https://github.com/headwindz/public-holidays/issues) or [Pull Request](https://github.com/headwindz/public-holidays/pulls).
## License
This project is open source and available under the MIT License.