We get questions about countries and subdivisions quite frequently so we thought it would be good to put together a guide explaining what they are and how they work here on Holiday API.
Countries are the top most grouping in which you can query holidays from our system. There are nearly 250 countries that make up the planet Earth, and with different governments and cultures, each one has it's own unique set of holidays and observance.
You can query holidays from our service be passing in a country
parameter with the country you're interested in.
When requesting holidays for a country, the holidays of the subdivisions are not included by default. This is because holidays at the subdivision level are not public holidays defined at the national or federal level.
For example, let's say you query Canada. You won’t get British Columbia Day, because it's actually specific to some of the subdivisions, and isn't a public holiday at the national level.
Lucky for you, we've eliminated most of this complexity. If you choose a plan
with access to subdivision data, you can simply include the
subdivisions flag to return all national and regional holidays for
a country.
A subdivision is [usually] a region of a country. In the United States, subdivisions are states, but there's also the District of Columbia, which is a district.
In the United Kingdom, subdivisions can be nations OR countries depending on which you are referring to. New Zealand calls them regions, and like the US, has a single outlier, Chatham Islands Territory, known as a "special island authority".
As you can see, things get complicated pretty quickly and vary country to country.
In addition to the wide variety of naming conventions, the subdivisions themselves can have their own unique holidays. These holidays are in addition to the national holidays that are defined at the country level.
Canada is a great example, as British Columbia Day is a widely celebrated holiday, but every province (yet another type of subdivision) has it's own name for it. Some provinces, like Ontario and Nova Scotia, don't consider the holiday a public holiday, while Nunavut, Alberta and others do.
To request holidays for a subdivision, you can pass in the subdivision's code
in the country parameter.
Additionally, you could also pass in the subdivisions parameter
when requesting a top level country, which will tell our system to include the
holidays for all of the country's subdivisions in the response.
When requesting a country and it's subdivision's holidays, you should expect to see some duplicate holidays in the mix, each keyed with their respective subdivision(s).
When scoping out the needs of your project, you will need to determine if country data will be sufficient, or if you will also need access to the larger dataset of subdivision specific holidays and observances.
Based on that, you can then choose the right plan that best fits with your requirements.
You can learn more about how to interact with Holiday API by checking out our developer documentation.
