Skip to content

๐ŸŒŽ Worldwide public holiday (REST API)

License

Notifications You must be signed in to change notification settings

nmarkezic/Nager.Date

ย 
ย 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

Build status

๐Ÿ“† Nager.Date - Official Website

Nager.Date is a popular project to query holidays. We currently support over 100 countries.
The project is based on .NET and provides a public REST Api for accessing the data.
You can find an overview of the supported countries here.

๐Ÿ“ฃ Announcement

Starting May 1, 2022, the Docker container and the NuGet package will require a License Key provided to the sponsors of this project. The public WebApi will remain freely accessible.

How can I use it?

Using the Swagger definition, they can have a client created for their programming language. You can find the information in our Api section. More Informations about client generation you can find here

Examples

.NET/C# (click to expand)
using System;
using System.Net.Http;
using System.Text.Json;

var jsonSerializerOptions = new JsonSerializerOptions { PropertyNameCaseInsensitive = true };

using var httpClient = new HttpClient();
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) {
      String json = new RestTemplate().getForObject("https://date.nager.at/api/v3/publicholidays/2022/US", String.class);
      JsonElement rootJsonElement = new JsonParser().parse(json);
      JsonArray publicHolidays = rootJsonElement.getAsJsonArray();
      Iterator<JsonElement> iterator = publicHolidays.iterator();
      while (iterator.hasNext()) {
        JsonElement publicHoliday = (JsonElement)iterator.next();
        System.out.println(publicHoliday);
      }
    }
}

build.gradle

apply plugin:'application'
mainClassName = 'Main'

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

repositories {
    jcenter()
}

dependencies {
    compile("org.springframework.boot:spring-boot-starter-web:2.6.7");
    compile("com.google.code.gson:gson:2.9");
}

For our sponsors, we also offer a Docker container and a NuGet package

nuget

The nuget package is available via NuGet

PM> install-package Nager.Date
Code Examples (click to expand)

Examples for .NET (nuget package)

Set the license key

DateSystem.LicenseKey = "LicenseKey1234";

Get all publicHolidays of a country and year

var publicHolidays = DateSystem.GetPublicHolidays(2021, "DE");
foreach (var publicHoliday in publicHolidays)
{
    //publicHoliday...
    //publicHoliday.Date -> The date
    //publicHoliday.LocalName -> The local name
    //publicHoliday.Name -> The english name
    //publicHoliday.Fixed -> Is this public holiday every year on the same date
    //publicHoliday.Global -> Is this public holiday in every county (federal state)
    //publicHoliday.Counties -> Is the public holiday only valid for a special county ISO-3166-2 - Federal states
    //publicHoliday.Type -> Public, Bank, School, Authorities, Optional, Observance
}

Get all publicHolidays for a date range

var startDate = new DateTime(2016, 5, 1);
var endDate = new DateTime(2021, 5, 31);
var publicHolidays = DateSystem.GetPublicHolidays(startDate, endDate, CountryCode.DE);
foreach (var publicHoliday in publicHolidays)
{
	//publicHoliday...
}

Check if a date is a public holiday

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

Check if a date is a weekend day

var date = new DateTime(2021, 1, 1);
if (DateSystem.IsWeekend(date, CountryCode.DE))
{
    Console.WriteLine("Is weekend");
}

docker

If high availability is important for you and you want to avoid access to the Internet, we can also offer you your own Docker container.

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:80 nager/nager-date

Areas of Application

  • telephone systems
  • carrier (land transport)
  • time recording

Blog Posts

Mark Seemann - Simple holidays

Alternative projects

Language Project Supported Countries (January 2019)
PHP yasumi 34
JavaScript date-holidays 142
Java jollyday 64
.NET Holiday 21
Python python-holidays 34
Python workalendar 59

About

๐ŸŒŽ Worldwide public holiday (REST API)

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • C# 100.0%