API

The API is available at https://api.opencovid.ca. See the guide below for how to construct API queries.

Navigation

Welcome
License
Acknowledgements
Issues, Suggestions and Code Availability
Basic Usage
   Data types
Time Series Data
Summary
Individual-level Data
Supplementary Data (Other)
Version
Appendix
   Notes
   Two-letter province codes
   Health region codes

Welcome

Welcome to the API documentation for the COVID-19 Canada Open Data Working Group dataset. The goal of the API is to provide an alternative method of accessing the dataset available in our GitHub repository. All results are returned as JSON.

License

The COVID-19 Open Data Working Group dataset is available under the Creative Commons Attribution 4.0 International license.

Acknowledgements

API programming by Jean-Paul R. Soucy and Farbod Abolhassani. API design by Jean-Paul R. Soucy, Isha Berry and Farbod Abolhassani. Dataset by the COVID-19 Open Data Working Group (see About Us).

Issues, Suggestions and Code Availability

The code for the API is available on GitHub. Please submit issues and suggestions here or by email to: ccodwg [at] gmail [dot] com.

Basic Usage

The API is capable of returning five types of data: time series data, a summary of all data for a particular day, individual-level data, supplementary data (“other”) and the date and time the dataset was last updated. The API is available at https://api.opencovid.ca. By default, this URL returns the summary data for Canada for the most recent day that data are available and the date and time the dataset was last updated (see Summary for more details).

Each data type is capable of taking one or more parameters. Begin your parameter string with ? and join parameters with &. See sample queries for examples.

Data types

Data type URI
Time series data /timeseries
Cumulative and daily totals for all data on a selected day /summary
Individual-level data /individual
Supplementary data (e.g., correspondence files) /other
Date and time the dataset was last updated /version

Time Series Data

https://api.opencovid.ca/timeseries

Time series data for cases, mortality, recovered, testing, active cases, vaccine administration and vaccine distribution are available. By default returns all province-level time series. Note that only case and mortality data are available as health region-level time series at present.

Parameters

The following parameters are available:

Parameter Type Description
stat String (cases, mortality, recovered, testing, active, avaccine, dvaccine or cvaccine) Return data only of the specified type
loc String (canada, prov, hr, a two-letter province code or a health region code - see appendix) (defalt: prov) Return data only from the specified geographic aggregation (see example queries)
date Date (YYYY-MM-DD or DD-MM-YYYY) Return data only from the specified date (e.g., 2020-07-23)
after Date (YYYY-MM-DD or DD-MM-YYYY) Return data on or after the specified date (e.g., 2020-07-23)
before Date (YYYY-MM-DD or DD-MM-YYYY) Return data on or before the specified date (e.g., 2020-07-23)
ymd Boolean (default: false) When true, return dates in YYYY-MM-DD format (otherwise, dates are returned in DD-MM-YYYY format)
missing String (null, na, nan or empty) (default: null) Missing values are given as either “NULL” (null, default), “NA” (na), “NaN” (nan) or “” (empty)
version Boolean (default: false) When true, return update date and time of dataset

Location

  • Two-letter province code: See list in appendix (e.g., ON for Ontario)
  • Health region code: See list in appendix (e.g., 3595 for Toronto Public Health)
  • canada: Time series aggregated for all of Canada
  • prov: Time series aggregated to the level of province (all provinces)
  • hr: Time series aggregated to the level of health region (all health regions)
  • Two-letter province code: See list in appendix (e.g., ON for Ontario)
  • Health region code: See list in appendix (e.g., 3595 for Toronto Public Health)

Note that there is currently no way to request only data with “Not Reported” health region from a specific province (“Not Reported” health region data for all provinces may be requested with loc=9999).

Sample queries

https://api.opencovid.ca/timeseries?stat=cases&loc=prov&date=01-09-2020

Sample data returned { "cases": [ { "cases": 164, "cumulative_cases": 14066, "date_report": "01-09-2020", "province": "Alberta" }, { "cases": 58, "cumulative_cases": 5849, "date_report": "01-09-2020", "province": "BC" }, { "cases": 18, "cumulative_cases": 1231, "date_report": "01-09-2020", "province": "Manitoba" }, { "cases": 0, "cumulative_cases": 191, "date_report": "01-09-2020", "province": "New Brunswick" }, { "cases": 0, "cumulative_cases": 269, "date_report": "01-09-2020", "province": "NL" }, { "cases": 0, "cumulative_cases": 1085, "date_report": "01-09-2020", "province": "Nova Scotia" }, { "cases": 0, "cumulative_cases": 0, "date_report": "01-09-2020", "province": "Nunavut" }, { "cases": 0, "cumulative_cases": 5, "date_report": "01-09-2020", "province": "NWT" }, { "cases": 135, "cumulative_cases": 44280, "date_report": "01-09-2020", "province": "Ontario" }, { "cases": 0, "cumulative_cases": 44, "date_report": "01-09-2020", "province": "PEI" }, { "cases": 122, "cumulative_cases": 62614, "date_report": "01-09-2020", "province": "Quebec" }, { "cases": 0, "cumulative_cases": 13, "date_report": "01-09-2020", "province": "Repatriated" }, { "cases": 3, "cumulative_cases": 1622, "date_report": "01-09-2020", "province": "Saskatchewan" }, { "cases": 0, "cumulative_cases": 15, "date_report": "01-09-2020", "province": "Yukon" } ] }

https://api.opencovid.ca/timeseries?stat=cases&loc=3595&after=01-03-2020&before=05-03-2020

Sample data returned { "cases": [ { "cases": 1, "cumulative_cases": 8, "date_report": "01-03-2020", "health_region": "Toronto", "province": "Ontario" }, { "cases": 0, "cumulative_cases": 8, "date_report": "02-03-2020", "health_region": "Toronto", "province": "Ontario" }, { "cases": 3, "cumulative_cases": 11, "date_report": "03-03-2020", "health_region": "Toronto", "province": "Ontario" }, { "cases": 0, "cumulative_cases": 11, "date_report": "04-03-2020", "health_region": "Toronto", "province": "Ontario" }, { "cases": 1, "cumulative_cases": 12, "date_report": "05-03-2020", "health_region": "Toronto", "province": "Ontario" } ] }

Summary

https://api.opencovid.ca/summary

Cumulative and daily totals for all data (cases, mortality, recovered, testing, active cases, vaccine administration or vaccine distribution) on a selected date or range of dates. By default returns province-level summaries for the most recent date in the dataset. Note that only case and mortality data are available as health region-level summaries at present.

Parameters

The following parameters are available:

Parameter Type Description
loc String (canada, prov, hr, a two-letter province code or a health region code - see appendix) (default: prov) Return data only from the specified geographic aggregation (see details below)
date Date (YYYY-MM-DD or DD-MM-YYYY) (default: the most recent date in the dataset) Return data only from the specified date (e.g., 2020-07-23)
after Date (YYYY-MM-DD or DD-MM-YYYY) Return data on or after the specified date (e.g., 2020-07-23)
before Date (YYYY-MM-DD or DD-MM-YYYY) Return data on or before the specified date (e.g., 2020-07-23)
ymd Boolean (default: false) When true, return dates in YYYY-MM-DD format (otherwise, dates are returned in DD-MM-YYYY format)
missing String (null, na, nan or empty) (default: null) Missing values are given as either “NULL” (null, default), “NA” (na), “NaN” (nan) or “” (empty)
version Boolean (default: false) When true, return update date and time of dataset

Location

  • canada: Time series aggregated for all of Canada
  • prov: Time series aggregated to the level of province (all provinces)
  • hr: Time series aggregated to the level of health region (all health regions)
  • Two-letter province code: See list in appendix (e.g., ON for Ontario)
  • Health region code: See list in appendix (e.g., 3595 for Toronto Public Health)

Note that there is currently no way to request only data with “Not Reported” health region from a specific province (“Not Reported” health region data for all provinces may be requested with loc=9999).

Sample query

https://api.opencovid.ca/summary?date=01-09-2020

Sample data returned { "summary": [ { "active_cases": 1398, "active_cases_change": 28, "cases": 164, "cumulative_cases": 14066, "cumulative_deaths": 241, "cumulative_recovered": 12427, "cumulative_testing": 976423, "date": "01-09-2020", "deaths": 2, "province": "Alberta", "recovered": 134, "testing": 9340, "testing_info": "NULL" }, { "active_cases": 1135, "active_cases_change": -42, "cases": 58, "cumulative_cases": 5849, "cumulative_deaths": 209, "cumulative_recovered": 4505, "cumulative_testing": 369162, "date": "01-09-2020", "deaths": 1, "province": "BC", "recovered": 99, "testing": 2527, "testing_info": "NULL" }, { "active_cases": 458, "active_cases_change": -10, "cases": 18, "cumulative_cases": 1231, "cumulative_deaths": 14, "cumulative_recovered": 759, "cumulative_testing": 138060, "date": "01-09-2020", "deaths": 0, "province": "Manitoba", "recovered": 28, "testing": 561, "testing_info": "NULL" }, { "active_cases": 3, "active_cases_change": -1, "cases": 0, "cumulative_cases": 191, "cumulative_deaths": 2, "cumulative_recovered": 186, "cumulative_testing": 61929, "date": "01-09-2020", "deaths": 0, "province": "New Brunswick", "recovered": 1, "testing": 407, "testing_info": "NULL" }, { "active_cases": 1, "active_cases_change": 0, "cases": 0, "cumulative_cases": 269, "cumulative_deaths": 3, "cumulative_recovered": 265, "cumulative_testing": 32200, "date": "01-09-2020", "deaths": 0, "province": "NL", "recovered": 0, "testing": 258, "testing_info": "NULL" }, { "active_cases": 6, "active_cases_change": -1, "cases": 0, "cumulative_cases": 1085, "cumulative_deaths": 65, "cumulative_recovered": 1014, "cumulative_testing": 77296, "date": "01-09-2020", "deaths": 0, "province": "Nova Scotia", "recovered": 1, "testing": 504, "testing_info": "NULL" }, { "active_cases": 0, "active_cases_change": 0, "cases": 0, "cumulative_cases": 0, "cumulative_deaths": 0, "cumulative_recovered": 0, "cumulative_testing": 2321, "date": "01-09-2020", "deaths": 0, "province": "Nunavut", "recovered": 0, "testing": 0, "testing_info": "NULL" }, { "active_cases": 0, "active_cases_change": 0, "cases": 0, "cumulative_cases": 5, "cumulative_deaths": 0, "cumulative_recovered": 5, "cumulative_testing": 3911, "date": "01-09-2020", "deaths": 0, "province": "NWT", "recovered": 0, "testing": 0, "testing_info": "NULL" }, { "active_cases": 3063, "active_cases_change": 42, "cases": 135, "cumulative_cases": 44280, "cumulative_deaths": 2848, "cumulative_recovered": 38369, "cumulative_testing": 2989888, "date": "01-09-2020", "deaths": 1, "province": "Ontario", "recovered": 92, "testing": 23545, "testing_info": "NULL" }, { "active_cases": 0, "active_cases_change": -3, "cases": 0, "cumulative_cases": 44, "cumulative_deaths": 0, "cumulative_recovered": 44, "cumulative_testing": 26811, "date": "01-09-2020", "deaths": 0, "province": "PEI", "recovered": 3, "testing": 1856, "testing_info": "NULL" }, { "active_cases": 1414, "active_cases_change": 35, "cases": 122, "cumulative_cases": 62614, "cumulative_deaths": 5762, "cumulative_recovered": 55438, "cumulative_testing": 1114354, "date": "01-09-2020", "deaths": 2, "province": "Quebec", "recovered": 85, "testing": 6167, "testing_info": "NULL" }, { "active_cases": 0, "active_cases_change": 0, "cases": 0, "cumulative_cases": 13, "cumulative_deaths": "NULL", "cumulative_recovered": 13, "cumulative_testing": "NULL", "date": "01-09-2020", "deaths": "NULL", "province": "Repatriated", "recovered": 0, "testing": "NULL", "testing_info": "NULL" }, { "active_cases": 31, "active_cases_change": -3, "cases": 3, "cumulative_cases": 1622, "cumulative_deaths": 24, "cumulative_recovered": 1567, "cumulative_testing": 119567, "date": "01-09-2020", "deaths": 0, "province": "Saskatchewan", "recovered": 6, "testing": 503, "testing_info": "NULL" }, { "active_cases": 0, "active_cases_change": 0, "cases": 0, "cumulative_cases": 15, "cumulative_deaths": 0, "cumulative_recovered": 15, "cumulative_testing": 2603, "date": "01-09-2020", "deaths": 0, "province": "Yukon", "recovered": 0, "testing": 41, "testing_info": "NULL" } ] }

https://api.opencovid.ca/summary?loc=canada&date=01-09-2020

Sample data returned { "summary": [ { "active_cases": 7509, "active_cases_change": 45, "cases": 500, "cumulative_cases": 131284, "cumulative_deaths": 9168, "cumulative_recovered": 114607, "cumulative_testing": 5914525, "date": "01-09-2020", "deaths": 6, "province": "Canada", "recovered": 449, "testing": 45709, "testing_info": "NULL" } ] }

Individual-level Data

https://api.opencovid.ca/individual

This route is temporarily disabled. Please download these data from our GitHub repository in the meantime.

Individual-level case and mortality data are available.

Parameters

The following parameters are available:

Parameter Type Description
stat String (cases or mortality) Return data only of the specified type
loc String (a two-letter province code, or a health region code - see appendix) Return data only from the specified province or health region (see example queries)
date Date (YYYY-MM-DD or DD-MM-YYYY) Return data only from the specified date (e.g., 2020-07-23)
after Date (YYYY-MM-DD or DD-MM-YYYY) Return data on or after the specified date (e.g., 2020-07-23)
before Date (YYYY-MM-DD or DD-MM-YYYY) Return data on or before the specified date (e.g., 2020-07-23)
ymd Boolean (default: false) When true, return dates in YYYY-MM-DD format (otherwise, dates are returned in DD-MM-YYYY format)
missing String (null, na, nan or empty) (default: null) Missing values are given as either “NULL” (null, default), “NA” (na), “NaN” (nan) or “” (empty)
extra Boolean (default: true) When true, join abbreviated columns (e.g., “case_source” or “death_source”, found in the directories “cases_extra” or “mortality_extra”)
version Boolean (default: false) When true, return update date and time of dataset

Location

  • Two-letter province code: See list in appendix (e.g., ON for Ontario)
  • Health region code: See list in appendix (e.g., 3595 for Toronto Public Health)

Note that there is currently no way to request only data with “Not Reported” health region from a specific province (“Not Reported” health region data for all provinces may be requested with loc=9999).

Sample query

https://api.opencovid.ca/individual?stat=cases&date=25-01-2020

Sample data returned { "cases": [ { "additional_info": "NULL", "additional_source": "NULL", "age": "50-59", "case_id": 1, "case_source": "(1) https://news.ontario.ca/mohltc/en/2020/01/ontario-confirms-first-case-of-wuhan-novel-coronavirus.html ;(2) https://globalnews.ca/news/6497313/coronavirus-timeine-cases-canada/; (3) https://globalnews.ca/news/6462626/coronavirus-toronto-hospital/", "country": "Canada", "date_report": "25-01-2020", "health_region": "Toronto", "locally_acquired": "NULL", "method_note": 0, "province": "Ontario", "provincial_case_id": 1, "report_week": "19-01-2020", "sex": "Male", "travel_history_country": "China", "travel_yn": "1" } ] }

Supplementary Data (Other)

https://api.opencovid.ca/other

Supplementary data such as correspondence files. By default returns all supplementary data.

  • prov: Correspondence file between province names used in our dataset and alternative province names; also, province-level population data
  • hr: Correspondence file between health region names used in our dataset and alternative health region names; also, health region-level population data
  • age_cases: Correspondence file between ages given in individual-level case data and ages displayed on our dashboard
  • age_mortality: Correspondence file between ages given in individual-level mortality data and ages displayed on our dashboard

Parameters

The following parameters are availablena:

Parameter Type Description
stat String (prov, hr, age_cases, age_mortality) Return data only of the specified type
missing String (null, na, nan or empty) (default: null) Missing values are given as either “NULL” (null, default), “NA” (na), “NaN” (nan) or “” (empty)
version Boolean (default: false) When true, return update date and time of dataset

Sample query

https://api.opencovid.ca/other?stat=prov

Sample data returned { "prov": [ { "pop": 4371316, "province": "Alberta", "province_full": "Alberta", "province_short": "AB" }, { "pop": 5071336, "province": "BC", "province_full": "British Columbia", "province_short": "BC" }, { "pop": 1369465, "province": "Manitoba", "province_full": "Manitoba", "province_short": "MB" }, { "pop": 776827, "province": "New Brunswick", "province_full": "New Brunswick", "province_short": "NB" }, { "pop": 521542, "province": "NL", "province_full": "Newfoundland and Labrador", "province_short": "NL" }, { "pop": 44826, "province": "NWT", "province_full": "Northwest Territories", "province_short": "NT" }, { "pop": 971395, "province": "Nova Scotia", "province_full": "Nova Scotia", "province_short": "NS" }, { "pop": 38780, "province": "Nunavut", "province_full": "Nunavut", "province_short": "NU" }, { "pop": 14566547, "province": "Ontario", "province_full": "Ontario", "province_short": "ON" }, { "pop": 156947, "province": "PEI", "province_full": "Prince Edward Island", "province_short": "PE" }, { "pop": 8484965, "province": "Quebec", "province_full": "Quebec", "province_short": "QC" }, { "pop": 1174462, "province": "Saskatchewan", "province_full": "Saskatchewan", "province_short": "SK" }, { "pop": 40854, "province": "Yukon", "province_full": "Yukon", "province_short": "YT" }, { "pop": "NULL", "province": "Repatriated", "province_full": "Repatriated", "province_short": "RP" } ] }

Version

https://api.opencovid.ca/version

Date and time the dataset was last updated (YYYY-MM-DD HH:MM TZ).

Parameters

Parameter Type Description
dateonly Boolean (default: false) When true, returns only the update date (YYYY-MM-DD) of the dataset.

Sample query

https://api.opencovid.ca/version

Sample data returned 2021-01-25 21:34 EST

Appendix

Notes

  • For date parameters (date, after, before), entry in ISO 8601 format (YYYY-MM-DD) is supported, but DD-MM-YYYY format is encouraged to match the date format of the output.

Two-letter province codes

Province name Two-letter code Province name in dataset
Alberta AB Alberta
British Columbia BC BC
Manitoba MB Manitoba
New Brunswick NB New Brunswick
Newfoundland and Labrador NL NL
Northwest Territories NT NWT
Nova Scotia NS Nova Scotia
Nunavut NU Nunavut
Ontario ON Ontario
Prince Edward Island PE PEI
Quebec QC Quebec
Saskatchewan SK Saskatchewan
Yukon YT Yukon
Repatriated RP Repatriated

Health region codes

Province Health region name Health region code
Alberta Calgary 4832
Alberta Central 4833
Alberta Edmonton 4834
Alberta North 4835
Alberta South 4831
BC Fraser 591
BC Interior 592
BC Island 593
BC Northern 594
BC Vancouver Coastal 595
Manitoba Interlake-Eastern 4603
Manitoba Northern 4604
Manitoba Prairie Mountain 4602
Manitoba Southern Health 4605
Manitoba Winnipeg 4601
New Brunswick Zone 1 (Moncton area) 1301
New Brunswick Zone 2 (Saint John area) 1302
New Brunswick Zone 3 (Fredericton area) 1303
New Brunswick Zone 4 (Edmundston area) 1304
New Brunswick Zone 5 (Campbellton area) 1305
New Brunswick Zone 6 (Bathurst area) 1306
New Brunswick Zone 7 (Miramichi area) 1307
NL Central 1012
NL Eastern 1011
NL Labrador-Grenfell 1014
NL Western 1013
Nova Scotia Zone 1 - Western 1201
Nova Scotia Zone 2 - Northern 1202
Nova Scotia Zone 3 - Eastern 1203
Nova Scotia Zone 4 - Central 1204
Nunavut Nunavut 6201
NWT NWT 6101
Ontario Algoma 3526
Ontario Brant 3527
Ontario Chatham-Kent 3540
Ontario Durham 3530
Ontario Eastern 3558
Ontario Grey Bruce 3533
Ontario Haldimand-Norfolk 3534
Ontario Haliburton Kawartha Pineridge 3535
Ontario Halton 3536
Ontario Hamilton 3537
Ontario Hastings Prince Edward 3538
Ontario Huron Perth 3539
Ontario Kingston Frontenac Lennox & Addington 3541
Ontario Lambton 3542
Ontario Leeds Grenville and Lanark 3543
Ontario Middlesex-London 3544
Ontario Niagara 3546
Ontario North Bay Parry Sound 3547
Ontario Northwestern 3549
Ontario Ottawa 3551
Ontario Peel 3553
Ontario Peterborough 3555
Ontario Porcupine 3556
Ontario Renfrew 3557
Ontario Simcoe Muskoka 3560
Ontario Southwestern 3575
Ontario Sudbury 3561
Ontario Thunder Bay 3562
Ontario Timiskaming 3563
Ontario Toronto 3595
Ontario Waterloo 3565
Ontario Wellington Dufferin Guelph 3566
Ontario Windsor-Essex 3568
Ontario York 3570
PEI Prince Edward Island 1100
Quebec Abitibi-Témiscamingue 2408
Quebec Bas-Saint-Laurent 2401
Quebec Capitale-Nationale 2403
Quebec Chaudière-Appalaches 2412
Quebec Côte-Nord 2409
Quebec Estrie 2405
Quebec Gaspésie-Îles-de-la-Madeleine 2411
Quebec Lanaudière 2414
Quebec Laurentides 2415
Quebec Laval 2413
Quebec Mauricie 2404
Quebec Montérégie 2416
Quebec Montréal 2406
Quebec Nord-du-Québec 2410
Quebec Nunavik 2417
Quebec Outaouais 2407
Quebec Saguenay 2402
Quebec Terres-Cries-de-la-Baie-James 2418
Saskatchewan Central 473
Saskatchewan Far North 471
Saskatchewan North 472
Saskatchewan Regina 475
Saskatchewan Saskatoon 474
Saskatchewan South 476
Yukon Yukon 6001
All Provinces Not Reported 9999