Skip to content
Permalink
main
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time
openapi: 3.0.0
info:
title: Canada Holidays API
version: 1.6.0
description: 'This API lists all 31 public holidays for all 13 provinces and territories in Canada, including federal holidays.'
contact:
name: Paul Craig
url: 'https://canada-holidays.ca/api'
email: paul@pcraig3.ca
license:
name: MIT
url: 'https://github.com/pcraig3/hols/blob/main/LICENSE'
servers:
- url: 'https://canada-holidays.ca'
paths:
/api/v1:
get:
summary: root
tags:
- root
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: A welcome message
example: Hello / Bonjour!
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: 'https://canada-holidays.ca/api/v1/'
description: Root domain
holidays:
type: object
properties:
href:
type: string
example: 'https://canada-holidays.ca/api/v1/holidays'
description: Domain to get all holidays
provinces:
type: object
properties:
href:
type: string
example: 'https://canada-holidays.ca/api/v1/provinces'
description: Domain to get all provinces
spec:
type: object
properties:
href:
type: string
example: 'https://canada-holidays.ca/api/v1/spec'
examples:
/:
value:
message: Hello / Bonjour! Welcome to the Canada Holidays API / Bienvenue dans l’API canadienne des jours fériés
_links:
self:
href: 'https://canada-holidays.ca/api/v1/'
holidays:
href: 'https://canada-holidays.ca/api/v1/holidays'
provinces:
href: 'https://canada-holidays.ca/api/v1/provinces'
spec:
href: 'https://canada-holidays.ca/api/v1/spec'
operationId: Root
description: Returns a welcome message.
/api/v1/holidays:
get:
summary: Get all holidays
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
type: object
properties:
holidays:
type: array
items:
$ref: '#/components/schemas/Holiday'
examples:
/holidays:
value:
holidays:
- id: 1
date: '2022-01-01'
nameEn: New Year’s Day
nameFr: Jour de l’An
federal: 1
observedDate: '2022-01-03'
provinces:
- id: AB
nameEn: Alberta
nameFr: Alberta
sourceLink: 'https://www.alberta.ca/alberta-general-holidays.aspx#jumplinks-1'
sourceEn: General holidays in Alberta
- id: BC
nameEn: British Columbia
nameFr: Colombie-Britannique
sourceLink: 'https://www2.gov.bc.ca/gov/content/employment-business/employment-standards-advice/employment-standards/statutory-holidays#body'
sourceEn: Statutory Holidays in British Columbia
- id: MB
nameEn: Manitoba
nameFr: Manitoba
sourceLink: 'https://www.gov.mb.ca/labour/standards/doc,gen-holidays-after-april-30-07,factsheet.html#q12'
sourceEn: General holidays in Manitoba
- id: NB
nameEn: New Brunswick
nameFr: Nouveau-Brunswick
sourceLink: 'https://www2.gnb.ca/content/gnb/en/departments/elg/local_government/content/governance/content/days_of_rest_act/faq.html#2'
sourceEn: 10 prescribed days of rest
- id: NL
nameEn: Newfoundland and Labrador
nameFr: Terre-Neuve-et-Labrador
sourceLink: 'https://gist.github.com/pcraig3/81dff348ddf52777c9f918c3032531bd'
sourceEn: Public holidays in Newfoundland
- id: NT
nameEn: Northwest Territories
nameFr: Territoires du Nord-Ouest
sourceLink: 'https://www.ece.gov.nt.ca/en/services/employment-standards/frequently-asked-questions#Statutory%20Holidays'
sourceEn: 'Employment Standards, Northwest Territories'
- id: NS
nameEn: Nova Scotia
nameFr: Nouvelle-Écosse
sourceLink: 'https://novascotia.ca/lae/employmentrights/holidaychart.asp'
sourceEn: Paid holidays in Nova Scotia
- id: NU
nameEn: Nunavut
nameFr: Nunavut
sourceLink: 'https://nu-lsco.ca/faq-s?tmpl=component&faqid=11'
sourceEn: Nunavut General Holidays
- id: 'ON'
nameEn: Ontario
nameFr: Ontario
sourceLink: 'https://www.ontario.ca/document/your-guide-employment-standards-act-0/public-holidays'
sourceEn: Ontario Public holidays
- id: PE
nameEn: Prince Edward Island
nameFr: Île-du-Prince-Édouard
sourceLink: 'https://www.princeedwardisland.ca/en/information/economic-growth-tourism-and-culture/paid-holidays'
sourceEn: PEI Paid Holidays
- id: QC
nameEn: Quebec
nameFr: Québec
sourceLink: 'https://www2.gouv.qc.ca/entreprises/portail/quebec/ressourcesh?lang=fr&g=ressourcesh&sg=personnel&t=o&e=2318829344:3908165687'
sourceEn: 'Jours fériés, chômés et payés'
- id: SK
nameEn: Saskatchewan
nameFr: Saskatchewan
sourceLink: 'https://www.saskatchewan.ca/business/employment-standards/public-statutory-holidays/list-of-saskatchewan-public-holidays'
sourceEn: Saskatchewan Public Holidays
- id: YT
nameEn: Yukon
nameFr: Yukon
sourceLink: 'https://yukon.ca/en/doing-business/employer-responsibilities/find-yukon-statutory-holiday'
sourceEn: Yukon statutory holiday dates
- id: 2
date: '2022-02-21'
nameEn: Louis Riel Day
nameFr: Journée Louis Riel
federal: 0
observedDate: '2022-02-21'
provinces:
- id: MB
nameEn: Manitoba
nameFr: Manitoba
sourceLink: 'https://www.gov.mb.ca/labour/standards/doc,gen-holidays-after-april-30-07,factsheet.html#q12'
sourceEn: General holidays in Manitoba
operationId: Holidays
description: Returns Canadian public holidays. Each holiday lists the regions that observe it.
parameters:
- schema:
type: integer
default: 2022
minimum: 2017
maximum: 2026
in: query
description: A calendar year
name: year
allowEmptyValue: true
- schema:
type: string
enum:
- '1'
- '0'
- 'true'
- 'false'
in: query
name: federal
description: 'A boolean parameter. If true or 1, will return only federal holidays. If false or 0, will return no federal holidays.'
allowEmptyValue: true
- schema:
type: string
enum:
- '1'
- '0'
- 'true'
- 'false'
default: 'false'
in: query
name: optional
description: 'A boolean parameter. If false or 0 (default), will return only legislated holidays. If true or 1, will return optional holidays from Alberta and BC.'
allowEmptyValue: true
tags:
- holidays
/api/v1/provinces:
get:
summary: Get all provinces
tags:
- provinces
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
type: object
properties:
provinces:
type: array
items:
$ref: '#/components/schemas/Province'
examples:
/provinces:
value:
provinces:
- id: AB
nameEn: Alberta
nameFr: Alberta
sourceLink: 'https://www.alberta.ca/alberta-general-holidays.aspx#jumplinks-1'
sourceEn: Alberta general holidays
holidays:
- id: 1
date: '2020-01-01'
nameEn: New Year’s Day
nameFr: Jour de l’An
federal: 1
observedDate: '2020-01-01'
- id: 4
date: '2020-02-17'
nameEn: Family Day
nameFr: Fête de la famille
federal: 0
observedDate: '2020-02-17'
nextHoliday:
id: 11
date: '2020-05-18'
nameEn: Victoria Day
nameFr: Fête de la Reine
federal: 1
observedDate: '2020-05-18'
- id: BC
nameEn: British Columbia
nameFr: Colombie-Britannique
sourceLink: 'https://www2.gov.bc.ca/gov/content/employment-business/employment-standards-advice/employment-standards/statutory-holidays'
sourceEn: Statutory Holidays
holidays:
- id: 1
date: '2020-01-01'
nameEn: New Year’s Day
nameFr: Jour de l’An
federal: 1
observedDate: '2020-01-01'
- id: 4
date: '2020-02-17'
nameEn: Family Day
nameFr: Fête de la famille
federal: 0
observedDate: '2020-02-17'
nextHoliday:
id: 11
date: '2020-05-18'
nameEn: Victoria Day
nameFr: Fête de la Reine
federal: 1
observedDate: '2020-05-18'
operationId: Provinces
parameters:
- schema:
type: integer
default: 2022
minimum: 2017
maximum: 2026
in: query
description: A calendar year
name: year
allowEmptyValue: true
- schema:
type: string
enum:
- '1'
- '0'
- 'true'
- 'false'
default: 'false'
in: query
name: optional
description: 'A boolean parameter. If false or 0 (default), will return only legislated holidays. If true or 1, will return optional holidays from Alberta and BC.'
allowEmptyValue: true
description: Returns provinces and territories in Canada. Each province or territory lists its associated holidays.
'/api/v1/provinces/{provinceId}':
get:
summary: Get a province or territory by abbreviation
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
type: object
properties:
province:
$ref: '#/components/schemas/Province'
examples:
/provinces/MB:
value:
province:
id: MB
nameEn: Manitoba
nameFr: Manitoba
sourceLink: 'https://www.gov.mb.ca/labour/standards/doc,gen-holidays-after-april-30-07,factsheet.html#q12'
sourceEn: General holidays in Manitoba
holidays:
- id: 1
date: '2022-01-01'
nameEn: New Year’s Day
nameFr: Jour de l’An
federal: 1
observedDate: '2022-01-03'
- id: 2
date: '2022-02-21'
nameEn: Louis Riel Day
nameFr: Journée Louis Riel
federal: 0
observedDate: '2022-02-21'
- id: 7
date: '2022-04-15'
nameEn: Good Friday
nameFr: Vendredi saint
federal: 1
observedDate: '2022-04-15'
- id: 11
date: '2022-05-23'
nameEn: Victoria Day
nameFr: Fête de la Reine
federal: 1
observedDate: '2022-05-23'
- id: 15
date: '2022-07-01'
nameEn: Canada Day
nameFr: Fête du Canada
federal: 1
observedDate: '2022-07-01'
- id: 26
date: '2022-09-05'
nameEn: Labour Day
nameFr: Fête du travail
federal: 1
observedDate: '2022-09-05'
- id: 28
date: '2022-10-10'
nameEn: Thanksgiving
nameFr: Action de grâce
federal: 1
observedDate: '2022-10-10'
- id: 30
date: '2022-12-25'
nameEn: Christmas Day
nameFr: Noël
federal: 1
observedDate: '2022-12-26'
nextHoliday:
id: 26
date: '2022-09-05'
nameEn: Labour Day
nameFr: Fête du travail
federal: 1
observedDate: '2022-09-05'
/provinces/MB?optional=true:
value:
province:
id: MB
nameEn: Manitoba
nameFr: Manitoba
sourceLink: 'https://www.gov.mb.ca/labour/standards/doc,gen-holidays-after-april-30-07,factsheet.html#q12'
sourceEn: General holidays in Manitoba
holidays:
- id: 1
date: '2022-01-01'
nameEn: New Year’s Day
nameFr: Jour de l’An
federal: 1
observedDate: '2022-01-03'
- id: 2
date: '2022-02-21'
nameEn: Louis Riel Day
nameFr: Journée Louis Riel
federal: 0
observedDate: '2022-02-21'
- id: 7
date: '2022-04-15'
nameEn: Good Friday
nameFr: Vendredi saint
federal: 1
observedDate: '2022-04-15'
- id: 8
date: '2022-04-18'
nameEn: Easter Monday
nameFr: Lundi de Pâques
federal: 1
observedDate: '2022-04-18'
optional: 1
- id: 11
date: '2022-05-23'
nameEn: Victoria Day
nameFr: Fête de la Reine
federal: 1
observedDate: '2022-05-23'
- id: 15
date: '2022-07-01'
nameEn: Canada Day
nameFr: Fête du Canada
federal: 1
observedDate: '2022-07-01'
- id: 23
date: '2022-08-01'
nameEn: Terry Fox Day
nameFr: Journée Terry Fox
federal: 0
observedDate: '2022-08-01'
optional: 1
- id: 26
date: '2022-09-05'
nameEn: Labour Day
nameFr: Fête du travail
federal: 1
observedDate: '2022-09-05'
- id: 27
date: '2022-09-30'
nameEn: National Day for Truth and Reconciliation
nameFr: Journée nationale de la vérité et de la réconciliation
federal: 1
observedDate: '2022-09-30'
optional: 1
- id: 28
date: '2022-10-10'
nameEn: Thanksgiving
nameFr: Action de grâce
federal: 1
observedDate: '2022-10-10'
- id: 29
date: '2022-11-11'
nameEn: Remembrance Day
nameFr: Jour du Souvenir
federal: 1
observedDate: '2022-11-11'
optional: 1
- id: 30
date: '2022-12-25'
nameEn: Christmas Day
nameFr: Noël
federal: 1
observedDate: '2022-12-26'
- id: 31
date: '2022-12-26'
nameEn: Boxing Day
nameFr: Lendemain de Noël
federal: 1
observedDate: '2022-12-27'
optional: 1
nextHoliday:
id: 23
date: '2022-08-01'
nameEn: Terry Fox Day
nameFr: Journée Terry Fox
federal: 0
observedDate: '2022-08-01'
optional: 1
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
$ref: '#/components/schemas/Error'
examples:
/provinces/100:
value:
error:
status: 400
message: 'Error: request.params.provinceId should be equal to one of the allowed values: AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT'
timestamp: '2020-04-28T04:02:38.813Z'
operationId: Province
description: Returns a Canadian province or territory with its associated holidays. Returns a 404 response for invalid abbreviations.
parameters:
- schema:
type: integer
default: 2022
minimum: 2017
maximum: 2026
in: query
description: A calendar year
name: year
allowEmptyValue: true
- schema:
type: string
default: 'false'
enum:
- '1'
- '0'
- 'true'
- 'false'
in: query
name: optional
description: 'A boolean parameter (AB and BC only). If false or 0 (default), will return only legislated holidays. If true or 1, will return optional holidays from Alberta and BC.'
allowEmptyValue: true
tags:
- provinces
parameters:
- schema:
type: string
enum:
- AB
- BC
- MB
- NB
- NL
- NS
- NT
- NU
- 'ON'
- PE
- QC
- SK
- YT
example: MB
name: provinceId
in: path
required: true
description: A Canadian province abbreviation
'/api/v1/holidays/{holidayId}':
parameters:
- schema:
type: integer
example: 2
minimum: 1
maximum: 31
name: holidayId
in: path
required: true
description: Primary key for a holiday
get:
summary: Get a holiday by id
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
type: object
properties:
holiday:
$ref: '#/components/schemas/Holiday'
examples:
/holidays/31:
value:
holiday:
id: 31
date: '2022-12-26'
nameEn: Boxing Day
nameFr: Lendemain de Noël
federal: 1
observedDate: '2022-12-27'
provinces:
- id: NL
nameEn: Newfoundland and Labrador
nameFr: Terre-Neuve-et-Labrador
sourceLink: 'https://gist.github.com/pcraig3/81dff348ddf52777c9f918c3032531bd'
sourceEn: Public holidays in Newfoundland
- id: 'ON'
nameEn: Ontario
nameFr: Ontario
sourceLink: 'https://www.ontario.ca/document/your-guide-employment-standards-act-0/public-holidays'
sourceEn: Ontario Public holidays
/holidays/31?optional=true:
value:
holiday:
id: 31
date: '2022-12-26'
nameEn: Boxing Day
nameFr: Lendemain de Noël
federal: 1
observedDate: '2022-12-27'
provinces:
- id: NL
nameEn: Newfoundland and Labrador
nameFr: Terre-Neuve-et-Labrador
sourceLink: 'https://gist.github.com/pcraig3/81dff348ddf52777c9f918c3032531bd'
sourceEn: Public holidays in Newfoundland
- id: 'ON'
nameEn: Ontario
nameFr: Ontario
sourceLink: 'https://www.ontario.ca/document/your-guide-employment-standards-act-0/public-holidays'
sourceEn: Ontario Public holidays
- id: AB
nameEn: Alberta
nameFr: Alberta
sourceLink: 'https://www.alberta.ca/alberta-general-holidays.aspx#jumplinks-1'
sourceEn: General holidays in Alberta
optional: 1
- id: BC
nameEn: British Columbia
nameFr: Colombie-Britannique
sourceLink: 'https://www2.gov.bc.ca/gov/content/employment-business/employment-standards-advice/employment-standards/statutory-holidays#body'
sourceEn: Statutory Holidays in British Columbia
optional: 1
- id: MB
nameEn: Manitoba
nameFr: Manitoba
sourceLink: 'https://www.gov.mb.ca/labour/standards/doc,gen-holidays-after-april-30-07,factsheet.html#q12'
sourceEn: General holidays in Manitoba
optional: 1
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
$ref: '#/components/schemas/Error'
examples:
/holidays/100:
value:
error:
status: 400
message: 'Error: request.params.holidayId should be <= 31'
timestamp: '2020-04-28T03:59:56.605Z'
operationId: Holiday
description: Returns one Canadian statutory holiday by integer id. Returns a 404 response for invalid ids.
parameters:
- schema:
type: integer
default: 2022
minimum: 2017
maximum: 2026
in: query
description: A calendar year
name: year
allowEmptyValue: true
- schema:
type: string
default: 'false'
enum:
- '1'
- '0'
- 'true'
- 'false'
in: query
name: optional
description: 'A boolean parameter. If false or 0 (default), will return provinces for which this is a legislated holiday. If true or 1, will return provinces which optionally celebrate this holiday.'
allowEmptyValue: true
tags:
- holidays
components:
schemas:
Holiday:
title: Holiday
type: object
description: 'A Canadian holiday. Includes a name, the literal date of the holiday, the observed date of the holiday (ie, accommodating for weekends), and a list of regions that observe this holiday.'
x-examples:
/holidays/31?optional=true:
holiday:
id: 31
date: '2022-12-26'
nameEn: Boxing Day
nameFr: Lendemain de Noël
federal: 1
observedDate: '2022-12-27'
provinces:
- id: NL
nameEn: Newfoundland and Labrador
nameFr: Terre-Neuve-et-Labrador
sourceLink: 'https://gist.github.com/pcraig3/81dff348ddf52777c9f918c3032531bd'
sourceEn: Public holidays in Newfoundland
- id: 'ON'
nameEn: Ontario
nameFr: Ontario
sourceLink: 'https://www.ontario.ca/document/your-guide-employment-standards-act-0/public-holidays'
sourceEn: Ontario Public holidays
- id: AB
nameEn: Alberta
nameFr: Alberta
sourceLink: 'https://www.alberta.ca/alberta-general-holidays.aspx#jumplinks-1'
sourceEn: General holidays in Alberta
optional: 1
- id: BC
nameEn: British Columbia
nameFr: Colombie-Britannique
sourceLink: 'https://www2.gov.bc.ca/gov/content/health/practitioner-professional-resources/msp/claim-submission-payment/designated-holidays-and-close-off-dates'
sourceEn: Government Holidays in British Columbia
optional: 1
properties:
id:
type: integer
description: Primary key for a holiday
example: 2
minimum: 1
maximum: 31
date:
type: string
description: 'ISO date: the literal date of the holiday'
format: date
example: '2020-12-26'
nameEn:
type: string
description: English name
example: Louis Riel Day
nameFr:
type: string
description: French name
example: Journée Louis Riel
federal:
type: integer
description: Whether this holiday is observed by federally-regulated industries.
enum:
- 1
- 0
format: binary
observedDate:
type: string
description: 'ISO date: when this holiday is observed'
format: date
example: '2020-12-28'
provinces:
type: array
items:
$ref: '#/components/schemas/Province'
optional:
type: integer
format: binary
enum:
- 1
description: 'Whether this is a province-wide statutory holiday, or one that is optional for employers.'
required:
- id
- date
- nameEn
- nameFr
- federal
- observedDate
Province:
title: Province
type: object
x-examples:
/provinces/SK:
province:
id: SK
nameEn: Saskatchewan
nameFr: Saskatchewan
sourceLink: 'https://www.saskatchewan.ca/business/employment-standards/public-statutory-holidays/list-of-saskatchewan-public-holidays'
sourceEn: Saskatchewan Public Holidays
holidays:
- id: 1
date: '2022-01-01'
nameEn: New Year’s Day
nameFr: Jour de l’An
federal: 1
observedDate: '2022-01-03'
- id: 4
date: '2022-02-21'
nameEn: Family Day
nameFr: Fête de la famille
federal: 0
observedDate: '2022-02-21'
- id: 7
date: '2022-04-15'
nameEn: Good Friday
nameFr: Vendredi saint
federal: 1
observedDate: '2022-04-15'
- id: 11
date: '2022-05-23'
nameEn: Victoria Day
nameFr: Fête de la Reine
federal: 1
observedDate: '2022-05-23'
- id: 15
date: '2022-07-01'
nameEn: Canada Day
nameFr: Fête du Canada
federal: 1
observedDate: '2022-07-01'
- id: 21
date: '2022-08-01'
nameEn: Saskatchewan Day
nameFr: Jour de Saskatchewan
federal: 0
observedDate: '2022-08-01'
- id: 26
date: '2022-09-05'
nameEn: Labour Day
nameFr: Fête du travail
federal: 1
observedDate: '2022-09-05'
- id: 28
date: '2022-10-10'
nameEn: Thanksgiving
nameFr: Action de grâce
federal: 1
observedDate: '2022-10-10'
- id: 29
date: '2022-11-11'
nameEn: Remembrance Day
nameFr: Jour du Souvenir
federal: 1
observedDate: '2022-11-11'
- id: 30
date: '2022-12-25'
nameEn: Christmas Day
nameFr: Noël
federal: 1
observedDate: '2022-12-26'
nextHoliday:
id: 21
date: '2022-08-01'
nameEn: Saskatchewan Day
nameFr: Jour de Saskatchewan
federal: 0
observedDate: '2022-08-01'
description: 'A Canadian province or territory '
properties:
id:
type: string
enum:
- AB
- BC
- MB
- NB
- NL
- NS
- NT
- NU
- 'ON'
- PE
- QC
- SK
- YT
example: MB
description: Canadian province abbreviations
nextHoliday:
$ref: '#/components/schemas/Holiday'
provinces:
type: array
items:
$ref: '#/components/schemas/Holiday'
nameFr:
type: string
description: French name
example: Manitoba
nameEn:
type: string
description: English name
example: Manitoba
sourceLink:
type: string
example: 'https://www.gov.mb.ca/labour/standards/doc,gen-holidays-after-april-30-07,factsheet.html#q12'
format: uri
pattern: https+
description: URL to public holidays reference for this region
sourceEn:
type: string
description: Name of reference page with public holidays for this region
example: What are the general holidays in Manitoba?
optional:
type: integer
description: Whether this province optionally observes a given holiday.
format: binary
enum:
- 1
required:
- id
- nameFr
- nameEn
- sourceLink
- sourceEn
Error:
title: Error
type: object
x-examples:
/holidays/100:
error:
status: 400
message: 'Bad Request: request.params.holidayId should be <= 31'
timestamp: '2020-04-28T03:59:12.427Z'
properties:
status:
type: integer
example: 404
minimum: 100
maximum: 599
description: An HTTP status code
message:
type: string
example: 'Error: No holiday with id “100”'
description: An error message
timestamp:
type: string
format: date-time
example: '2020-04-27T05:41:10.710Z'
description: A UTC ISO timestamp
securitySchemes: {}
tags:
- name: holidays
description: Get holiday(s) with associated provinces
- name: provinces
description: Get province(s) with associated holidays
- name: root
description: Get welcome message and links