The Docker container provides the same REST API as nagerholidays.com, but runs on your own infrastructure. Existing integrations only need a different base URL.

REST API

curl https://nagerholidays.com/api/v4/Holidays/US/2026

The API documentation provides a complete overview of all available endpoints. You can generate a client in your preferred programming language with the OpenAPI Generator. For .NET there is the official client Nager.Holiday.

Examples for .NET, Python, JavaScript, PHP and Java: doc/examples/rest-api.md

Docker

The Docker container is available via Docker Hub. It provides the same REST API as nagerholidays.com, operated on your own infrastructure without a dependency on our servers.

docker run -p 8080:8080 -e LICENSE_KEY=YOUR_LICENSE_KEY nager/nager-date

All REST API examples work unchanged, only the base URL changes:

curl http://localhost/api/v4/Holidays/US/2026

NuGet

dotnet add package Nager.Date

HolidaySystem.LicenseKey = "TheLicenseKey";

var holidays = HolidaySystem.GetHolidays(2026, CountryCode.DE);

More examples: doc/examples/offline-nuget.md

Holiday types

What variants of holidays are supported by Nager.Date

Special Date Types (Dynamic & Unconfirmed Dates)

To better handle complex calendar systems and official announcements, the project distinguishes certain holidays with special characteristics:

• Roughly Date: This applies to holidays translated from calendars like the HijriCalendar. Because these dates rely on local moon sightings, they are subject to change and may shift 1–2 days forward or backward at short notice.
• Tentative Date: This applies to holidays that are highly likely to occur on the specified date but are still pending official confirmation or proclamation by the respective government.

Release and Support Lifecycle

Here you can see how long the product will be supported and when the End of Life (EOL) is planned.

Data precision

Holidays are provided at country level and, where they differ regionally, for the first-level subdivisions of a country according to ISO 3166-2 (e.g. states, provinces, cantons). More detailed levels such as districts or cities are not supported.

Since every country names its subdivisions differently, they are always returned in the field subdivisionCodes (REST API v4) or SubdivisionCodes (NuGet package). If a holiday applies to the entire country, nationalHoliday is true and subdivisionCodes is empty.

[!NOTE] REST API v3 still uses the older field name counties for the same data.

Limitation Regarding Islamic Holidays

Some Islamic holidays (e.g., Eid al-Fitr, Eid al-Adha) are based on the Islamic lunar calendar and are often determined by local moon sightings. As this depends on weather conditions and geographic location, these dates cannot be reliably calculated in advance. Therefore, such holidays are not included in this project.

Areas of Application

There are several business fields in which it is important to know the holidays in different countries.

• E-commerce: If an online retailer sells its products in different countries, it should know the holidays in these countries to adjust delivery times and customer service accordingly.
• Travel industry: A tour operator should know the holidays of the countries to which it offers trips, to alert its customers to special events or closed attractions.
• Staff scheduling: Companies with branches in several countries must know the holidays in each country to be able to plan their staff needs accordingly.
• Financial industry: Banks and financial institutions should know the holidays in the countries in which they conduct business to ensure that transfers and transactions are performed on time and to estimate the impact of holidays on the foreign exchange market.
• Logistics and supply chains: Companies managing logistics or supply chains across several countries, must know the holidays in these countries to adjust planning and supply chain decisions.
• Telephone systems: To automatically turn on the answering machine on holidays.
• Time recording: To automatically fill the missing hours with the normal working hours.

Articles about this project

• Mark Seemann - Simple holidays
• dotnetpro - Feiertagsrechner (German)