Canada Holidays API

The Canada Holidays API lists all 31 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: 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025, 2026

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 below describing the API, and a bite-sized brief overview if you keep reading.

OpenAPI (formerly Swagger)

The OpenAPI Specification is a broadly-adopted 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. As much as I know you would love to, 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}

None of the response object keys ever 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.

?year=2017|2018|2019|2020|2021|2022|2023|2024|2025|2026. Defaults to current year.
?federal=true|1|false|0. true or 1 returns only federal holidays; false or 0 returns everything but federal holidays.

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

'Optional' query parameter

There is 1 optional query parameter that currently applies only to Alberta, British Columbia, Manitoba, and Ontario. Alberta's official holidays page lists "optional" holidays, and British Columbia, Manitoba, and Ontario (ctrl+f "Remembrance Day") do something similar, so I am making them available via the API.

?optional=true|1|false|0. true or 1 returns all Alberta/BC/MB/ON holidays, including optional holidays; false or 0 returns Alberta/BC/MB/ON holidays as per usual: this is equivalent to not using "optional" at all.

Optional holidays don't show up by default, so existing calls won’t be affected.

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