Dayoff

Public holidays for 200+ countries, their states and regions, offline, in Elixir. The data and the rule grammar come from date-holidays and a daily sync keeps them current. No runtime dependencies.

Dayoff.holidays("BR", 2026, types: [:public])
# [%Dayoff.Holiday{date: ~D[2026-01-01], name: "Ano Novo", type: :public, rule: "01-01", ...}, ...]

Dayoff.holiday?(~D[2026-11-26], "US")
# true

Dayoff.on(~D[2026-12-25], "DE", state: "BY", language: "en") |> Enum.map(& &1.name)
# ["Christmas Day"]

Installation

def deps do
  [
    {:dayoff, "~> 0.1"}
  ]
end

Elixir 1.18 or newer.

Usage

Country codes are ISO 3166-1 alpha-2 strings ("US" or "us"). States and regions use the dataset's codes, listed by Dayoff.states/1 and Dayoff.regions/2.

Dayoff.countries(language: "en")["AT"]      # "Austria"
Dayoff.states("US")["CA"]                   # "California"
Dayoff.holidays("DE", 2026, state: "BY", region: "A")
Dayoff.holidays("US-CA", 2026)              # the state can ride along in the code
Dayoff.holidays("US", 2026, types: [:public, :bank])

A Dayoff.Holiday has its date, start and end as wall-clock times in the country's zone, the name in the country's language (or language:), a type (:public, :bank, :school, :optional, :observance), the rule it came from, whether it is a substitute? day and a note. Dayoff.on/3 gives the holidays covering a date or a NaiveDateTime, since some start in the afternoon or span days. Also there: languages/2, zones/2, day_off/2, weekend/2, rules/2 and version/0.

How it works

The data is one JSON file of rules like 4th thursday in November or substitutes 12-25 if saturday then previous friday, one per holiday. Dayoff parses them and evaluates them for the year you ask about, see the Rules guide. Every date is checked against date-holidays itself, holiday by holiday for all countries, states and regions. The guide lists the three places where dayoff deliberately differs.

mix dayoff.sync rebuilds the data from upstream master (needs Node). A workflow runs it daily and, when the upstream data changed and the tests pass, pushes a fix: commit that release-please turns into a patch release.

A holiday is wrong or missing

The data lives upstream in date-holidays, one YAML file per country under data/countries. Fix it there (their contributing guide explains the format) and dayoff picks it up within a day of the merge. Open an issue here only when the dates differ from what date-holidays gives.

License

Code: Apache-2.0, Copyright 2026 George Guimarães. The holiday data is from commenthol/date-holidays under CC BY-SA 3.0, the rule grammar is a port of date-holidays-parser (ISC), see NOTICE. Releases follow Conventional Commits, see RELEASE.md.