Public holidays for 200+ countries, states and regions, offline.
The data and the rule grammar come from date-holidays and are synced from its master branch daily.
iex> Dayoff.countries()["BR"]
"Brasil"
iex> Dayoff.states("US")["CA"]
"California"Country codes are ISO 3166-1 alpha-2 strings, "US" or "us".
States and regions use the upstream codes, see states/1 and regions/2.
A state can also ride along in the country code: "US-CA".
Summary
Types
A country code string, US or us, optionally with the state as in US-CA.
Options shared by the lookup functions.
Functions
Every country in the dataset, by code, named in its own first language or
in :language when given.
The weekly day off as a weekday atom, nil when the dataset doesn't say.
Whether anything in on/3 matches.
The holidays of a year for a country, state or region, sorted by start.
The languages holiday names are available in for a country, state or
region, most specific first, always ending in "en".
The holidays covering a moment. With a Date, every holiday whose start
and end overlap that calendar day; with a NaiveDateTime, the holidays
running at that wall-clock time in the country's zone. Takes the same
options as holidays/3.
The regions of a state, by code.
The merged rule map for a country, state or region: rule string to its
attributes (name, type, substitute, active, disable, enable,
note). Mostly for debugging and for tests.
The states (or top-level regions, for countries that only have those) of a country, by code.
The upstream commits the shipped data was built from.
The weekend as weekday atoms. From the dataset's weekend field when it
has one, otherwise the single day off, otherwise Saturday and Sunday.
The IANA timezones of a country, state or region. The first one is the zone holiday times are expressed in.
Types
@type country() :: String.t()
A country code string, US or us, optionally with the state as in US-CA.
Options shared by the lookup functions.
:state- state or region code inside the country ("CA","07"):region- region code inside the state ("A"in"DE","BY"):language- ISO 639-1 code for names; falls back to the country's languages and then English
Functions
Every country in the dataset, by code, named in its own first language or
in :language when given.
iex> Dayoff.countries(language: "en")["DE"]
"Germany"The weekly day off as a weekday atom, nil when the dataset doesn't say.
iex> Dayoff.day_off("BD")
:friday@spec holiday?(Date.t() | NaiveDateTime.t(), country(), keyword()) :: boolean()
Whether anything in on/3 matches.
iex> Dayoff.holiday?(~D[2026-12-25], "BR")
true
iex> Dayoff.holiday?(~D[2026-02-14], "US", types: [:public])
false@spec holidays(country(), integer(), keyword()) :: [Dayoff.Holiday.t()]
The holidays of a year for a country, state or region, sorted by start.
Options: :state, :region, :language (see option/0) and :types,
a list of Dayoff.Holiday.type/0 to keep, all five by default.
iex> [thanksgiving] = Dayoff.holidays("US", 2026) |> Enum.filter(&(&1.rule == "4th thursday in November"))
iex> {thanksgiving.date, thanksgiving.name, thanksgiving.type}
{~D[2026-11-26], "Thanksgiving Day", :public}
iex> Dayoff.holidays("BR", 2026, types: [:public]) |> Enum.map(& &1.date) |> Enum.take(3)
[~D[2026-01-01], ~D[2026-04-03], ~D[2026-04-21]]The languages holiday names are available in for a country, state or
region, most specific first, always ending in "en".
iex> Dayoff.languages("AT")
["de-at", "de", "en"]@spec on(Date.t() | NaiveDateTime.t(), country(), keyword()) :: [Dayoff.Holiday.t()]
The holidays covering a moment. With a Date, every holiday whose start
and end overlap that calendar day; with a NaiveDateTime, the holidays
running at that wall-clock time in the country's zone. Takes the same
options as holidays/3.
iex> Dayoff.on(~D[2026-12-25], "BR") |> Enum.map(& &1.name)
["Natal"]
iex> Dayoff.on(~N[2026-12-24 15:00:00], "BR") |> Enum.map(& &1.name)
["Noite de Natal"]
iex> Dayoff.on(~D[2026-12-23], "BR")
[]The regions of a state, by code.
iex> Dayoff.regions("DE", "BY")["A"]
"Stadt Augsburg"The merged rule map for a country, state or region: rule string to its
attributes (name, type, substitute, active, disable, enable,
note). Mostly for debugging and for tests.
The states (or top-level regions, for countries that only have those) of a country, by code.
iex> Dayoff.states("AT")["9"]
"Wien"@spec version() :: map()
The upstream commits the shipped data was built from.
iex> Dayoff.version() |> Map.keys() |> Enum.sort()
["holidays", "holidays_version", "parser", "synced_at"]The weekend as weekday atoms. From the dataset's weekend field when it
has one, otherwise the single day off, otherwise Saturday and Sunday.
iex> Dayoff.weekend("BD")
[:friday, :saturday]
iex> Dayoff.weekend("BR")
[:sunday]The IANA timezones of a country, state or region. The first one is the zone holiday times are expressed in.
iex> Dayoff.zones("US", state: "CA")
["America/Los_Angeles"]