Nager.Date: Public Holiday Data Through REST, NuGet, or Docker

Choosing Between Nager.Date Access Models

Nager.Date addresses the problem of keeping application calendars aligned with public holidays across more than 200 countries. The alternatives are a hosted REST API, an offline .NET package, and a Docker container. This range lets developers choose between a shared online data source and software deployed within their own infrastructure.

The REST API is useful to applications written outside C#. The README includes examples for PHP, Java, and Python, while the API documentation supports client generation through OpenAPI Generator. This makes Nager.Date a cross-language data service rather than only a .NET library. The online model is suitable when requests can reach `nagerholidays.com` and the adopter accepts the availability and update characteristics of a hosted service.

The NuGet package is the most direct option for an offline .NET application. Docker serves teams that already deploy containerized services and need a local endpoint rather than a package embedded in application code. The README states that both the offline NuGet and Docker options require a license key obtained through sponsorship. They are therefore not unrestricted, credential-free distributions under the repository's MIT license.

The documented country coverage should be checked before adoption. Nager.Date links to a coverage page at `nagerholidays.com/country/coverage`, which is the relevant place to verify support for a particular country and its subdivisions. The README does not promise identical geographic depth for every country, so a general claim of coverage for more than 200 countries does not answer every regional requirement.

Nager.Date REST Requests and Returned Holiday Data

The hosted API is queried with a year and country code. The C# example requests public holidays for the United States in 2022, while the Java example requests Switzerland for the same year. The returned JSON represents an array of holiday objects rather than a single date or a preformatted calendar.

The README's Python example is the shortest documented first call. It sends an HTTP request, decodes the JSON response, and prints the `date` field for every returned holiday.

import json
import requests

response = requests.get(
    'https://nagerholidays.com/api/v3/publicholidays/2022/US'
)
public_holidays = json.loads(response.content)

for public_holiday in public_holidays:
    print(public_holiday['date'])

A successful response provides a JSON array whose records contain holiday dates. The documented object examples also expose `localName`, `name`, `countryCode`, `global`, `counties`, and `types`. Applications should not assume that every result means the same thing to a business. A returned entry may describe a public, bank, school, authority, optional, or observance holiday.

The offline .NET model adds explicit fields for several important distinctions. `NationalHoliday` indicates whether a holiday applies throughout the country, while `SubdivisionCodes` identifies entries limited to particular ISO 3166-2 subdivisions. `ObservedDate` can differ from the nominal `Date`. A scheduling system may need to consider both dates, but the application must define which one controls staffing, delivery eligibility, or form validation.

The REST documentation provides the full endpoint list through its API reference. The README does not document authentication, rate limits, retry rules, uptime guarantees, response caching, or historical availability limits. A production integration therefore has unanswered operational questions beyond the basic request format.

Installing the Offline Nager.Date Package

The README directs offline.NET users to the `Nager.Date` package on NuGet. Its Package Manager Console example is:

PM> install-package Nager.Date

After adding the package, an application must configure the sponsor-issued license key before using the offline API. The README uses `TheLicenseKey` as a placeholder:

HolidaySystem.LicenseKey = "TheLicenseKey";

A first real query can request all holidays for Germany in 2024:

var holidays = HolidaySystem.GetHolidays(2024, "DE");
foreach (var holiday in holidays)
{
    // holiday...
}

This call should produce a collection of holiday objects for Germany. Relevant fields include the nominal `Date`, `ObservedDate`, `LocalName`, `EnglishName`, `NationalHoliday`, `SubdivisionCodes`, and `HolidayTypes`. The result can therefore drive more detailed rules than a simple list of dates.

The README also documents direct license validation. `LicenseHelper.CheckLicenseKey` identifies an invalid key through a null result, while `ValidUntil` can be compared with `DateTime.Today` to detect expiration. The documentation does not explain how to request the key, how renewal works, or whether deployment environments need separate keys. Those are concrete licensing and operational points to settle before putting the package into production.

Using Date Ranges and Single-Date Holiday Checks

Applications that operate over a reporting period can request a date range instead of making separate annual queries. The README uses Germany as the example country and spans May 2016 through May 2024.

var startDate = new DateTime(2016, 5, 1);
var endDate = new DateTime(2024, 5, 31);
var holidays = HolidaySystem.GetHolidays(
    startDate,
    endDate,
    CountryCode.DE
);

The returned collection can feed reporting, availability checks, or scheduling logic. A caller should examine each holiday's type before treating it as a company-wide closure. For example, an optional or observance entry may require a different policy from a national public holiday. The package exposes the metadata needed to make that distinction, but it does not prescribe a business policy.

For one-date validation, `HolidaySystem.IsPublicHoliday` provides a boolean result. The README demonstrates the API with Germany and January 1, 2024.

var date = new DateTime(2024, 1, 1);
if (HolidaySystem.IsPublicHoliday(date, CountryCode.DE))
{
    Console.WriteLine("Is a public holiday");
}

This is useful for order validation, staff planning, or calendar display, but the calling application remains responsible for time-zone handling. The documentation uses `DateTime` examples and does not specify conversion rules for UTC timestamps or locations that observe different time zones. If an input instant can cross midnight, the application should establish whether it is checking its local civil date, the country's local date, or a UTC date.

The package also exposes weekend checking in the README, but the visible example is truncated. It therefore does not provide enough detail here to reproduce that operation without guessing its exact method signature.

Docker Deployment, Licensing, and Upgrade Considerations

The Docker option places Nager.Date behind `nager/nager-date`, which is linked from the README on Docker Hub. This deployment model can fit container-oriented infrastructure and avoids routing every holiday lookup to the public REST host. However, the README does not provide a `docker run` command, image tag, port mapping, environment-variable list, configuration file, or health-check endpoint. Those deployment details cannot be reconstructed from the project documentation without guessing.

Licensing is a material constraint. The repository declares the MIT license, but the README separately states that the offline NuGet and Docker variants require a sponsor license key. The repository's license file does not by itself establish the terms attached to those hosted distribution artifacts. An adopter needs the applicable package and container terms before deciding whether sponsorship cost and key management fit the deployment model. This review does not provide legal advice or infer terms that are not published in the README.

The README points to the coverage page for supported geographies, while the repository includes `CHANGELOG.md` for release history. The last push was on 2026-10-14. Releases v2.45.3, v2.45.2, and v2.45.1 were published on 2026-10-14, 2026-10-09, and 2026-09-24. Those facts establish recent release activity, but they do not reveal the annual cost of reviewing holiday-rule changes or the effort required to upgrade consumer applications.

The README does not document a compatibility matrix, long-term-support policy, schema migration guide, or procedure for upgrading a running container. For a hosted REST integration, API changes are also relevant to generated clients. The safest adoption decision therefore starts with the coverage page and a small set of application-specific holiday scenarios, including observed dates and subdivision-specific entries.

Editorial conclusion

Nager.Date is suitable for .NET teams that need country, date-range, observed-holiday, and subdivision queries, as well as applications that can consume a generated REST client. It is a weaker fit for projects requiring a free, credential-free embedded library or treating holiday data as authoritative without country-specific review. Check country coverage first, then compare returned dates, subdivision codes, and holiday types against the application rules.

Frequently asked questions

Official sources

1. License: MIT
2. nager/Nager.Date on GitHub
3. Project website
4. README
5. Releases