:calendar: Nager.Date - Official Website

Discover the convenience of easily accessing holidays from over 100 countries with Nager.Date. Our popular project utilizes the power of .NET and offers a user-friendly public REST API for seamless integration into your application.

You can find an overview of the supported countries here.

Need offline access to our functionality? No problem! We also provide solutions that allow you to use our services on your own infrastructure without an internet connection. Easily integrate our service into your system with the Docker container or the NuGet package. Both options require a license key. As a sponsor of nager, you get a license key.

How can I use it?

Easily generate a client in your preferred programming language by utilizing our API documentation, which provides a complete overview of all available endpoints. For more details on client generation, refer to the OpenAPI Generator documentation.

Examples

<details> <summary>.NET/C# (click to expand)</summary>

There are two ways to use our service

NuGet - Nager.Holiday

PM> install-package Nager.Holiday

Copy Code

using System;
using System.Net.Http;
using System.Text.Json;

var jsonSerializerOptions = new JsonSerializerOptions { PropertyNameCaseInsensitive = true };

using var httpClient = new HttpClient();
using var response = await httpClient.GetAsync("https://date.nager.at/api/v3/publicholidays/2022/US");
if (response.IsSuccessStatusCode)
{
    using var jsonStream = await response.Content.ReadAsStreamAsync();
    var publicHolidays = JsonSerializer.Deserialize<PublicHoliday[]>(jsonStream, jsonSerializerOptions);
}

class PublicHoliday
{
    public DateTime Date { get; set; }
    public string LocalName { get; set; }
    public string Name { get; set; }
    public string CountryCode { get; set; }
    public bool Global { get; set; }
    public string[] Counties { get; set; }
    public string[] Types { get; set; }
}

</details> <details> <summary>PHP (click to expand)</summary>

This example use the guzzle project

<?php
require_once 'vendor/autoload.php';
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://date.nager.at/api/v3/publicholidays/2022/US');
if ($response->getStatusCode() == 200) {
    $json = $response->getBody();
    print_r(json_decode($json));
}
?>

</details> <details> <summary>Java (click to expand)</summary>

This example use the springframework. Code tested with onecompiler.com

Main.java

import java.util.*;
import org.springframework.web.client.RestTemplate;
import com.google.gson.*;

public class Main {
  public static void main(String[] args) {
    System.out.println("get holidays");
    String json = new RestTemplate().getForObject("https://date.nager.at/api/v3/publicholidays/2022/CH", String.class);
    
    Gson gson = new Gson();
    PublicHoliday[] userArray = gson.fromJson(json, PublicHoliday[].class);  

    for(PublicHoliday publicHoliday : userArray) {
      System.out.print(publicHoliday.date);
      System.out.print(" ");
      System.out.print(publicHoliday.name);
      System.out.print(" ");
      System.out.print(String.join(",", publicHoliday.counties ?? new String[0]));
      System.out.print(" ");
      System.out.println(publicHoliday.localName);
    }
  }
}

PublicHoliday.java

public class PublicHoliday {
  public String date;
  public String localName;
  public String name;
  public String countryCode ;
  public Boolean fixed;
  public Boolean global;
  public String[] counties;
  public String[] types;
}

build.gradle

apply plugin:'application'
mainClassName = 'Main'

run { standardInput = System.in }
sourceSets { main { java { srcDir './' } } }

repositories {
  jcenter()
}

dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-web:2.6.7';
  implementation 'com.google.code.gson:gson:2.10.1';
}

</details> <details> <summary>Python (click to expand)</summary>

main.py

import json
import requests

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

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

</details>

Offline Solution

Don't let internet connectivity issues disrupt your workflow. Our offline solutions enable you to use our services on your own infrastructure without an internet connection. With a sponsorship you get the license key to use the variants locally without a dependency to our REST API.

NuGet

The NuGet package is available via NuGet<br>

PM> install-package Nager.Date

<details> <summary>Code Examples (click to expand)</summary>

Examples for .NET (NuGet package)

Set the license key

HolidaySystem.LicenseKey = "TheLicenseKey";

Check the license

var licenseKey = "TheLicenseKey";
var licenseInfo = Nager.Date.License.LicenseHelper.CheckLicenseKey(licenseKey);
if (licenseInfo is null)
{
    //license key invalid
    return;
}

if (licenseInfo.ValidUntil < DateTime.Today)
{
    //license key expired
    return;
}

Get all holidays of a country and year

var holidays = HolidaySystem.GetHolidays(2024, "DE");
foreach (var holiday in holidays)
{
    //holiday...
    //holiday.Date -> The date
    //holiday.ObservedDate -> The date on which the holiday is observed
    //holiday.LocalName -> The local name
    //holiday.EnglishName -> The english name
    //holiday.NationalHoliday -> Is this public holiday in every county (federal state)
    //holiday.SubdivisionCodes -> Is the public holiday only valid for a special county ISO-3166-2 - Federal states
    //holiday.HolidayTypes -> Public, Bank, School, Authorities, Optional, Observance
}

Get all holidays for a date range

var startDate = new DateTime(2016, 5, 1);
var endDate = new DateTime(2024, 5, 31);
var holidays = HolidaySystem.GetHolidays(startDate, endDate, CountryCode.DE);
foreach (var holiday in holidays)
{
	//holiday...
}

Check if a date is a public holiday

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

Checks if the given date falls on a weekend day

var date = new DateTime(2024, 1, 1);
if (WeekendSystem.IsWeekend(date, CountryCode.DE))
{
    Console.WriteLine("The date is in the weekend");
}

</details>

Docker

The Docker container is available via Docker Hub<br> To run a local instance of the Docker image run the following command<br> docker run -p 80:8080 nager/nager-date

Holiday types

What variants of holidays are supported by Nager.Date

| Type | Description | | ----------- | ------------------------------------------- | | Public | Public holiday | | Bank | Bank holiday, banks and offices are closed | | School | School holiday, schools are closed | | Authorities | Authorities are closed | | Optional | Majority of people take a day off | | Observance | Optional festivity, no paid day off |

Release and Support Lifecycle

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

| Product | Release Date | Supported | End of life | | -------------------------------- | ----------------------------------------- | --------- | ----------- | | WebApi v4 | under development | No | - | | WebApi v3 | 2021-05-18 | Yes | - | | WebApi v2 | 2019-02-10 | No | 2024-12-01 | | WebApi v1 | 2017-02-06 | No | 2024-06-24 | | Nuget Package v2 | 2024-03-07 | Yes | - | | Nuget Package v1 | 2014-08-15 | No | 2024-03-07 |

Data precision

There is no generally valid designation for the next administrative level of countries. "Nager.Date" supports the initial subdivision of a country, but we will not support a detailed level because the effort required is too high.

To keep it generally valid, we will treat this subdivision as SubdivisionCodes, this will replace the current designation Counties.

United States of America use States
Germany use States
Austria use States
Switzerland use Cantons
Brazil use States
Australia use States or Territories
Russia use Federal districts
Canada use Province or Territories

| Precision | Supported | | ---------------------------------------------------------------------------- | --------- | | Public Holidays for specific Country | Yes | | Holidays for Subdivisions based on ISO 3166-2 (first level) | Yes | | Holidays for Cities

Nager.Date

Install / Use

README