# nagerholidays.com

> Global Public Holidays platform providing interactive calendars, holiday reminders, long weekend planners for end-users, and a powerful REST API for developers.

## Overview

* nagerholidays.com powered by nager.date is a comprehensive, open-source platform for worldwide public holiday data, supporting over 200 countries.
* It serves end-users with interactive holiday calendars, deep-dive holiday information, a holiday reminder service, and smart long-weekend (bridgetime) planning.
* It serves developers through multiple integration options:
  * Community API (free public access)
  * Pro API (extended features requiring an API key)
  * Self-hostable Docker container
  * Native .NET NuGet package
* **Website:** https://nagerholidays.com
* **GitHub:** https://github.com/nager/Nager.Date
* **Data Source:** Community-contributed holiday rules via C# / .NET

---

## Documentation and Resources

The following resources provide detailed information on integrating and hosting the holiday service:

* [API Reference Documentation](https://nagerholidays.com/scalar/) - Full API specification for all endpoints.
* [GitHub Repository](https://github.com/nager/Nager.Date) - Source code, contribution guidelines, and country rules.
* [NuGet Package](https://www.nuget.org/packages/Nager.Date) - Official native .NET client library.
* [Docker Deployment Guide](https://github.com/nager/Nager.Date#docker) - Instructions for self-hosting the WebAPI container.

---

## User Features (Web Interface)

The website `https://nagerholidays.com` provides user-friendly tools for everyday users:
* **Holiday Calendars:** Interactive calendars to view public holidays by country and region.
* **Holiday Information:** Detailed insights into specific holidays, their meanings, and local names.
* **Holiday Reminder:** A service allowing users to get notified before upcoming public holidays.
* **Long Weekend Planner:** Calculates and displays the best "Long Weekends" (bridge days) to help users maximize their vacation time.

---

## Developer Integration Options & Licensing

* **Hosted API:** Ideal for non-.NET environments. Base URL is `https://nagerholidays.com`.
  * **Community API v4:** Public access, no API key required.
  * **Pro API v1:** Requires authentication via HTTP Header `x-api-key`. A valid API key is required for access.
* **NuGet Package (Nager.Date):** The native way for .NET developers. It allows local, high-performance holiday calculation completely offline without network overhead. **Requires a valid license key for integration and execution.**
* **Docker Container:** For developers who want to self-host the WebAPI infrastructure locally, offline, or within their own private cloud network. Image is available via Docker Hub. **Requires a valid license key for deployment and operation.**

---

## Key Differences: Community API v4 vs Pro API v1

| Feature | Community API v4 | Pro API v1 |
| :--- | :--- | :--- |
| **Authentication** | None | Requires API key (`x-api-key` header) |
| **Holiday ID** | Not available | Unique ID per holiday (e.g., `"DE-CHRISTMASDAY-01"`) |
| Names | Basic holiday name | Separate `localName` and `englishName` |
| Observed Dates | Limited | Available via `observedDate` |
| **Time Range** | Restricted to near-present years | **Extended range** further into the past and future |
| **Long Weekends** | Not available | Available |

---

## Key API Endpoints (Hosted or Self-Hosted)

### Community API v4

#### 1. Get Public Holidays
Returns the public holidays for a specific year and country.
* **Endpoint:** `/api/v4/Holidays/{countryCode}/{year}`
* **Method:** `GET`
* **Parameters:** `year` (int), `countryCode` (ISO 3166-1 alpha-2, e.g., `DE`, `AT`, `CH`)

#### 2. Get Available Countries
Returns a list of all supported countries.
* **Endpoint:** `/api/v4/Countries/Available`
* **Method:** `GET`

#### Community API v4 Data Model

### PublicHolidayV4Dto Object

```json
{
  "date": "2026-12-25",
  "name": "Christmas Day",
  "countryCode": "DE",
  "nationalHoliday": true,
  "subdivisionCodes": [
    "DE-BY"
  ],
  "holidayTypes": [
    "Public"
  ]
}
```

### Pro API v1

#### 1. Get Public Holidays

Returns extended public holiday information for a specific year and country.

* **Endpoint:** `/api/pro/v1/Holidays/{countryCode}/{year}`
* **Method:** `GET`
* **Authentication:** Required via HTTP Header `x-api-key`
* **Parameters:** `year` (int), `countryCode` (ISO 3166-1 alpha-2, e.g., `DE`, `AT`, `CH`)

#### 2. Get Available Countries

Returns all supported countries with extended metadata.

* **Endpoint:** `/api/pro/v1/Countries/Available`
* **Method:** `GET`
* **Authentication:** Required via HTTP Header `x-api-key`

#### Pro API v1 Data Model

### HolidayV1Dto Object

```json
{
  "id": "DE-CHRISTMASDAY-01",
  "date": "2026-12-25",
  "observedDate": "2026-12-25",
  "localName": "1. Weihnachtstag",
  "englishName": "Christmas Day",
  "countryCode": "DE",
  "nationalHoliday": true,
  "subdivisionCodes": [
    "DE-BY"
  ],
  "holidayTypes": [
    "Public"
  ]
}
```