holidays

Ruby Holidays Gem

Functionality to deal with holidays in Ruby.

Extends Ruby's built-in Date and Time classes and supports custom holiday definition lists.

All holiday definitions are maintained in the holidays/definitions repository. By default this gem returns statutory (formally government-defined) holidays. Culturally recognized but non-statutory holidays (such as Valentine's Day) are available via the :informal option. See the definitions syntax guide for details on how holidays are classified.

Installation

gem install holidays

Tested versions

This gem is tested with the following ruby versions:

• 3.3
• 3.4
• 4.0
• JRuby 10.0.5.0
• JRuby 10.1.0.0

Semver

This gem follows semantic versioning. The guarantee specifically covers:

• methods in the top-most Holidays namespace e.g. Holidays.
• the core extensions

Please note that we consider definition changes to be 'minor' bumps, meaning they are backwards compatible with your code but might give different holiday results!

Time zones

Time zones are ignored. This library assumes that all dates are within the same time zone.

Usage

This gem offers multiple ways to check for holidays for a variety of scenarios.

Checking a specific date

Get all holidays on April 25, 2008 in Australia:

Holidays.on(Date.new(2008, 4, 25), :au)
=> [{:name => 'ANZAC Day',...}]

You can check multiple regions in a single call:

Holidays.on(Date.new(2008, 1, 1), :us, :fr)
=> [{:name=>"New Year's Day", :regions=>[:us],...},
    {:name=>"Jour de l'an", :regions=>[:fr],...}]

You can leave off 'regions' to get holidays for any region in our definitions:

 Holidays.on(Date.new(2007, 4, 25))
=> [{:name=>"ANZAC Day", :regions=>[:au],...},
    {:name=>"Festa della Liberazione", :regions=>[:it],...},
    {:name=>"Dia da Liberdade", :regions=>[:pt],...}
    ...
   ]

Wildcard regions

A region ending in an underscore (e.g. :au_, :ca_) is a wildcard. It matches the parent country region and all of its sub-regions in a single call:

Holidays.on(Date.new(2017, 3, 13), :au_)
=> [{:name=>"Eight Hours Day", :regions=>[:au_tas],...},
    {:name=>"Labour Day", :regions=>[:au_vic],...},
    {:name=>"March Public Holiday", :regions=>[:au_sa],...},
    {:name=>"Canberra Day", :regions=>[:au_act],...}]

The same date queried with the plain :au region returns nothing, because none of those holidays are observed nation-wide:

Holidays.on(Date.new(2017, 3, 13), :au)
=> []

Use a wildcard when you want "this country and every sub-region it defines" without listing each sub-region explicitly.

Note that a wildcard always collapses to the top-level country region. The portion between the country prefix and the trailing underscore is ignored, so :au_vic_ behaves identically to :au_ (it loads every Australian sub-region, not just Victoria's). There is currently no way to wildcard-match only the children of a sub-region.

Checking a date range

Get all holidays during the month of July 2008 in Canada and the US:

from = Date.new(2008,7,1)
to = Date.new(2008,7,31)

Holidays.between(from, to, :ca, :us)
=> [{:name => 'Canada Day',...}
    {:name => 'Independence Day',...}]

Check for 'informal' holidays

You can pass the 'informal' flag to include holidays specified as informal in your results. See here for information on what constitutes 'informal' vs 'formal'.

By default this flag is turned off, meaning no informal holidays will be returned.

Get Valentine's Day in the US:

Holidays.on(Date.new(2018, 2, 14), :us, :informal)
=> [{:name=>"Valentine's Day",...}]

Leaving off 'informal' will mean that Valentine's Day is not returned:

Holidays.on(Date.new(2018, 2, 14), :us)
=> []

Get informal holidays during the month of February 2008 for any region:

from = Date.new(2008,2,1)
to = Date.new(2008,2,15)

Holidays.between(from, to, :informal)
=> [{:name => 'Valentine\'s Day',...}]

Check for 'observed' holidays

You can pass the 'observed' flag to include holidays that are observed on different days than they actually occur. See here for further explanation of 'observed'.

By default this flag is turned off, meaning no observed logic will be applied.

Get holidays that are observed on Monday July 2, 2007 in British Columbia, Canada:

Holidays.on(Date.new(2007, 7, 2), :ca_bc, :observed)
=> [{:name => 'Canada Day',...}]

Leaving off the 'observed' flag will mean that 'Canada Day' is not returned since it actually falls on Sunday July 1:

Holidays.on(Date.new(2007, 7, 2), :ca_bc)
=> []

Holidays.on(Date.new(2007, 7, 1), :ca_bc)
=> [{:name=>"Canada Day", :regions=>[:ca],...}]

Get all observed US Federal holidays between 2018 and 2019:

from = Date.new(2018,1,1)
to = Date.new(2019,12,31)

Holidays.between(from, to, :federalreserve, :observed)
=> [{:name => "New Year's Day"....}
    {:name => "Birthday of Martin Luther King, Jr"....}]

Check whether any holidays occur during work week

Check if there are any holidays taking place during a specified work week. 'Work week' is defined as the period of Monday through Friday of the week specified by the date.

Check whether a holiday falls during first week of the year for any region:

Holidays.any_holidays_during_work_week?(Date.new(2016, 1, 1))
=> true

You can also pass in informal or observed:

…

Find the next holiday(s) that will occur from a specific date

Get the next holidays occurring from February 23, 2016 for the US:

Holidays.next_holidays(3, [:us, :informal], Date.new(2016, 2, 23))
=> [{:name => "St. Patrick's Day",...}, {:name => "Good Friday",...}, {:name => "Easter Sunday",...}]

You can specify the number of holidays to return. This method will default to Date.today if no date is provided.

Find all holidays occurring starting from a specific date to the end of the year

Get all holidays starting from February 23, 2016 to end of year in the US:

Holidays.year_holidays([:ca_on], Date.new(2016, 2, 23))
=> [{:name=>"Good Friday",...},
    {:name=>"Easter Sunday",...},
    {:name=>"Victoria Day",...},
    {:name=>"Canada Day",...},
    {:name=>"Civic Holiday",...},
    {:name=>"Labour Day",...},
    {:name=>"Thanksgiving",...},
    {:name=>"Remembrance Day",...},
    {:name=>"Christmas Day",...},
    {:name=>"Boxing Day",...}]

This method will default to Date.today if no date is provided.

Return all available regions

Return all available regions:

Holidays.available_regions
=> [:ar, :at, ..., :sg] # this will be a big array

Return region names

Return the English name of every region:

Holidays.region_names
=> {:ar=>"Argentina", :at=>"Austria", ..., :sg=>"Singapore"} # this will be a big hash

Return the English name of a single region:

Holidays.region_name(:gb_eng)
=> "England"

Unknown regions return nil:

Holidays.region_name(:not_a_region)
=> nil

Names are the ISO 3166 English short names where one exists. Subregions and non-country regions (stock exchanges, central banks, shipping carriers) use their common English name.

Loading Custom Definitions on the fly

In addition to the provided definitions you can load custom definitions file on the fly and use them immediately.

To load custom 'Company Founding' holiday on June 1st:

Holidays.load_custom('/home/user/holiday_definitions/custom_holidays.yaml')
Holidays.on(Date.new(2013, 6, 1), :my_custom_region)
=> [{:name => 'Company Founding',...}]

Custom definition files must match the syntax of the existing definition files.

Multiple files can be loaded at the same time:

Holidays.load_custom(
  '/home/user/holidays/custom_holidays1.yaml',
  '/home/user/holidays/custom_holidays2.yaml'
)

Note that any tests: stanzas in a custom definition file are ignored by load_custom. Tests are only executed at build time for definitions contributed to the definitions repository, where rake generate turns them into the test suite. There is no runtime mechanism to run the tests embedded in a custom file loaded on the fly.

Extending Ruby's Date and Time classes

Date

To extend the 'Date' class:

require 'holidays/core_extensions/date'

class Date
  include Holidays::CoreExtensions::Date
end

Now you can check which holidays occur in Iceland on January 1, 2008:

d = Date.new(2008,7,1)

d.holidays(:is)
=> [{:name => 'Nýársdagur'}...]

Or lookup Canada Day in different regions:

d = Date.new(2008,7,1)

d.holiday?(:ca) # Canada
=> true

d.holiday?(:ca_bc) # British Columbia, Canada
=> true

d.holiday?(:fr) # France
=> false

Or return the new date based on the options:

d = Date.new(2008,7,1)
d.change(:year => 2016, :month => 1, :day => 1)
=> #

Or you can calculate the day of the month:

Date.calculate_mday(2015, 4, :first, 2)
=> 7

Time

require 'holidays/core_extensions/time'

class Time
  include Holidays::CoreExtensions::Time
end

Find end of month for given date:

d = Date.new(2016,8,1)
d.end_of_month
=> #

Caching Holiday Lookups

If you are checking holidays regularly you can cache your results for improved performance. Run this before looking up a holiday (e.g. in an initializer):

YEAR = 365 * 24 * 60 * 60
Holidays.cache_between(Time.now, Time.now + 2 * YEAR, :ca, :us, :observed)

Holidays for the regions specified within the dates specified will be pre-calculated and stored in-memory. Future lookups will be much faster.

How to contribute

See our contribution guidelines for information on how to help out!

Credits and code

• Started by @alexdunae 2007-2012
• Maintained by @hahahana, 2013
• Maintained by @ppeble, 2014-present
• Maintained by @ttwo32, 2016-present

Plus all of these wonderful contributors!