Nager.Date SDKs & Libraries: C# Clients & Community Tools (2026)

SDKs overview

Nager.Date provides a Public Holiday API designed to deliver holiday data for numerous countries. To streamline integration for developers, Nager.Date offers an official client library primarily for the .NET ecosystem. This client abstracts direct HTTP requests, managing API authentication, requests, and response parsing, thereby simplifying the process of incorporating holiday logic into applications built with C#. While the official support focuses on C#, the API's OpenAPI specification allows for the generation of client libraries in other languages using tools like Swagger Codegen, fostering potential community-driven SDKs.

The Nager.Date API is accessible via RESTful HTTP endpoints, returning data in JSON format. Developers can query public holidays based on country code and year. The API documentation, provided through Swagger UI, details all available endpoints, request parameters, and response structures, enabling developers to understand and interact with the API directly or through generated clients. Access to the API, including usage of SDKs, is subject to rate limits, with a free tier available for up to 500 requests per day, and various Nager.Date pricing plans for higher volumes.

Official SDKs by language

The primary official SDK for Nager.Date is developed for the .NET platform, specifically targeting C# developers. This client library is designed to offer a native experience for applications built within the .NET ecosystem. It encapsulates the complexities of HTTP communication, JSON serialization, and deserialization, allowing developers to interact with the Public Holiday API using idiomatic C# code. The official client is maintained by the Nager.Date team, ensuring compatibility with the latest API versions and features.

The .NET client is distributed via NuGet, the package manager for .NET, making it accessible for developers to integrate into their projects. This client library typically follows semantic versioning, providing clear indications of breaking changes or new features. Developers can refer to the Nager.Date API documentation for specific class structures and method signatures provided by the SDK.

Installation

Installing the official Nager.Date C# SDK is done through NuGet, the package manager for Microsoft development platforms, including .NET. This process integrates the library into your project, making its functionalities available for use. The following steps outline the installation process, suitable for various .NET development environments.

Using the .NET CLI

For projects managed with the .NET Command-Line Interface (CLI), you can add the Nager.Date.Api package directly from your terminal. Navigate to your project directory where the .csproj file is located and execute the following command:

dotnet add package Nager.Date.Api

This command fetches the latest stable version of the package from NuGet and adds a reference to it in your project file. For specific versions, you can append --version <VERSION_NUMBER> to the command.

Using NuGet Package Manager Console (Visual Studio)

In Visual Studio, developers can use the NuGet Package Manager Console to install packages. Open Visual Studio, navigate to Tools > NuGet Package Manager > Package Manager Console. In the console window, ensure your target project is selected in the 'Default project' dropdown, then run:

Install-Package Nager.Date.Api

This command performs the same action as the .NET CLI, adding the package reference to your project. The console provides immediate feedback on the installation status.

Using NuGet Package Manager GUI (Visual Studio)

Alternatively, Visual Studio offers a graphical user interface for managing NuGet packages. Right-click on your project in the Solution Explorer and select Manage NuGet Packages.... In the 'Browse' tab, search for Nager.Date.Api, select the package, and click 'Install'. This method provides a visual confirmation of the package being added.

After installation, the library's classes and methods become available for import and use within your C# code. Ensure your project targets a compatible .NET framework version as specified by the Nager.Date.Api package's dependencies, which are typically listed on its NuGet package page.

Quickstart example

This quickstart demonstrates how to use the official Nager.Date C# SDK to retrieve public holidays for a specific country and year. This example assumes you have already installed the Nager.Date.Api NuGet package in your .NET project.

First, you need to instantiate the Nager.Date client, which facilitates communication with the API. You can typically do this by creating an instance of NagerDateApi. Many modern .NET applications use dependency injection, where you might register the client in your Startup.cs or Program.cs file and then inject it into your services or controllers.

Here's a basic example demonstrating how to get holidays for Germany (DE) in the year 2026:

using Nager.Date.Api;
using System;
using System.Linq;
using System.Threading.Tasks;

public class HolidayRetriever
{
    private readonly NagerDateApi _nagerDateApi;

    public HolidayRetriever()
    {
        // In a real application, consider using HttpClientFactory and dependency injection.
        // For simplicity, we'll instantiate directly here.
        _nagerDateApi = new NagerDateApi(new HttpClient());
    }

    public async Task GetGermanHolidays(int year)
    {
        try
        {
            // The Nager.Date API client expects a two-letter ISO 3166-1 alpha-2 country code.
            // For Germany, this is "DE". For a list of supported countries, consult the
            // Nager.Date API documentation for country codes.
            var publicHolidays = await _nagerDateApi.ApiPublicHolidayGet(year, "DE");

            if (publicHolidays != null && publicHolidays.Any())
            {
                Console.WriteLine($"Public Holidays for Germany ({year}):");
                foreach (var holiday in publicHolidays.OrderBy(h => h.Date))
                {
                    Console.WriteLine($"  - {holiday.Date?.ToShortDateString()} - {holiday.LocalName} ({holiday.Name})");
                }
            }
            else
            {
                Console.WriteLine($"No public holidays found for Germany in {year} or an error occurred.");
            }
        }
        catch (ApiException ex)
        {
            Console.WriteLine($"API Error: {ex.StatusCode} - {ex.Message}");
            // Log the full response or additional details from ex.Response
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }

    public static async Task Main(string[] args)
    {
        var retriever = new HolidayRetriever();
        await retriever.GetGermanHolidays(2026);
        Console.WriteLine("\nPress any key to exit.");
        Console.ReadKey();
    }
}

This example initializes the NagerDateApi client and then calls the ApiPublicHolidayGet method, passing the year and the ISO 3166-1 alpha-2 country code for Germany. The returned list of PublicHolidayV2 objects contains details for each holiday, including its date, local name, and English name. Error handling is included to catch potential API exceptions (e.g., rate limits, invalid country codes) or general network issues. To get a comprehensive list of ISO 3166-1 alpha-2 country codes, refer to the official ISO online browsing platform.

For production applications, it is recommended to use HttpClientFactory for managing HttpClient instances, which helps in preventing common issues like socket exhaustion and ensures proper disposal of clients. You would typically register the NagerDateApi client in your .NET dependency injection container.

Community libraries

While Nager.Date officially supports a C# client, the nature of its RESTful API and the availability of an OpenAPI (formerly Swagger) specification mean that community members can generate and maintain client libraries for other programming languages. The OpenAPI specification provides a standardized, language-agnostic interface description, allowing tools like Swagger Codegen to automatically create client SDKs from the Nager.Date API definition.

These community-contributed libraries, while not officially supported by the Nager.Date team, can offer developers working in environments like Python, Java, JavaScript, Go, or Ruby a more integrated way to interact with the Public Holiday API. Potential benefits of using community libraries include:

• Language Idiomaticity: Libraries designed for a specific language often follow its conventions, making them easier to use for developers familiar with that language.
• Reduced Boilerplate: They abstract away HTTP request handling, JSON parsing, and error management, similar to official SDKs.
• Community Support: Users might find support and share solutions within the community channels relevant to the library's language.

Developers interested in finding or contributing to community libraries should typically search package repositories specific to their language (e.g., PyPI for Python, npm for Node.js, Maven Central for Java) using keywords like "Nager.Date" or "Public Holiday API client." It is important to evaluate community libraries for their maintenance status, documentation, and licensing before incorporating them into production applications, as their quality and longevity can vary. For developers creating their own clients, the OpenAPI specification available through the Nager.Date Swagger UI is the authoritative source for API endpoint details.