๐ 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.
Caution
The WebApi V2 will be shut down in December 2024
Please only use the latest WebApi V3
Easily create a client in your preferred programming language by utilizing our Swagger definition. Find all the necessary information in our API section. Get more details about client generation in the documentation.
.NET/C# (click to expand)
There are two ways to use our service
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 Fixed { get; set; }
public bool Global { get; set; }
public string[] Counties { get; set; }
public int? LaunchYear { get; set; }
public string[] Types { get; set; }
}
PHP (click to expand)
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));
}
?>
Java (click to expand)
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';
}
Python (click to expand)
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'])
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.
The NuGet package is available via NuGet
PM> install-package Nager.Date
Code Examples (click to expand)
HolidaySystem.LicenseKey = "LicenseKey1234";
var holidays = HolidaySystem.GetHolidays(2024, "DE");
foreach (var holiday in holidays)
{
//holiday...
//holiday.Date -> The date
//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
}
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...
}
var date = new DateTime(2024, 1, 1);
if (HolidaySystem.IsPublicHoliday(date, CountryCode.DE))
{
Console.WriteLine("Is a public holiday");
}
var date = new DateTime(2024, 1, 1);
if (WeekendSystem.IsWeekend(date, CountryCode.DE))
{
Console.WriteLine("The date is in the weekend");
}
The Docker container is available via Docker Hub
To run a local instance of the Docker image run the following command
docker run -p 80:8080 nager/nager-date
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 |
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
orTerritories
- Russia use
Federal districts
- Canada use
Province
orTerritories
Precision | Supported |
---|---|
Public Holidays for specific Country | Yes |
Holidays for Subdivisions based on ISO 3166-2 (first level) | Yes |
Holidays for Cities | No |
Holidays for Regions | No |
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.