Canada Holidays API

The Canada Holidays API lists all 32 public holidays for all 13 provinces and territories in Canada, including federal holidays.

👉 https://canada-holidays.ca/api/v1/

Features:

• Returns holidays with associated regions
• Returns regions with associated holidays
• Returns only federal holidays
• Returns only national holidays
• Returns "next" holiday for each region
• Returns holidays for years: 2013, …, 2026, … 2038

Plus(!) check out all these goodies you get for ✨ free ✨:

• It’s free (✨)
• Dedicated support channel
• Kind of bilingual (EN & FR)
• Pretty much compliant with the Government of Canada Standards on APIs (heck yes 🤙)
• Open source which is cool if you’re a nerd
• Documented with an OpenAPI spec which is even more cool for even nerdier nerds

Definitely use it for your billions of dollars mission-critical system.

Docs

If you know your way around a REST API with JSON responses, you’re in good shape. There's an OpenAPI spec describing the API, and a brief overview below.

OpenAPI (formerly Swagger)

The OpenAPI Specification is industry standard for describing APIs. The OpenAPI spec for this API is in a few places.

• Canada-Holidays-API.v1.yaml on GitHub
• At https://canada-holidays.ca/api/v1/spec
• canada-holidays on SwaggerHub

The SwaggerHub link includes an API explorer so you can give it a spin before you drive it off the lot.

Basic overview

There are 5 endpoints. All are GET requests. Regrettably, it’s not yet possible to PUT additional public holidays.

• /api/v1
• /api/v1/provinces
• /api/v1/provinces/{provinceId}
• /api/v1/holidays
• /api/v1/holidays/{holidayId}

Response keys never contain null values.

Query parameters

There are 2 (½) query parameters values you can use. Probably not on the root route but on others they will work.

1. year: Takes a single year from the following: 2023, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025, 2026, 2027, 2028, 2029, 2030, 2031, 2032, 2033, 2034, 2035, 2036, 2037, 2038. Defaults to the current year.
   • Example: ?year=2031
2. federal. true or 1 to return only federal holidays; false or 0 to return everything but federal holidays.
   • Example: ?federal=true

You can combine them and they will work (eg, /api/v1/holidays?year=2031&federal=true).

'Optional' query parameter

There is 1 optional query parameter that currently applies to Alberta, British Columbia, Manitoba, New Brunswick, Nova Scotia, Nunavut, Ontario, and Quebec. Alberta's official holidays page lists "optional" holidays, and British Columbia, Manitoba, New Brunswick, Nova Scotia, and Ontario (ctrl+f "Remembrance Day") do something similar, so I am making them available via the API. In Quebec, we can see this page of public servants’ holidays, which includes Jan 2nd Nunavut has a public service holiday for Truth and Reconciliation Day, so it’s basically an optional holiday (not everyone gets it).

• optional: true or 1 includes optional holidays; false or 0 doesn’t. By default, optional holidays are not included (equivalent to ?optional=false).

That should be enough to get you started. Remember, the design goal here is simple.