API

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

Navigation

Welcome
License
Acknowledgements
Basic Usage
   Data types
Individual-level Data
Time Series Data
Summary
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 Farbod Abolhassani and Jean-Paul R. Soucy. API design by Jean-Paul R. Soucy, Isha Berry, and Farbod Abolhassani. Dataset by the COVID-19 Open Data Working Group (see About Us).

Code availability

The code for the API is available on GitHub. A validation script to compare the dataset on GitHub and the data returned by the API can be found here.

Basic Usage

The API is capable of returning four types of data: individual-level data, time series data, a summary of all data for a particular day, 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
Individual-level data /individual
Time series data /timeseries
Cumulative and daily totals for all data on a selected day /summary
Date and time the dataset was last updated /version

Individual-level Data

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 (DD-MM-YYYY) Return data only from the specified date (e.g., 23-07-2020)
after Date (DD-MM-YYYY) Return data on or after the specified date (e.g., 23-07-2020)
before Date (DD-MM-YYYY) Return data on or before the specified date (e.g., 23-07-2020)
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.

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" } ] }

Time Series Data

Time series data for cases, mortality, recovered, testing, and active cases are available. By default returns province-level time series.

Parameters

The following parameters are available:

Parameter Type Description
stat String (cases, mortality, recovered, testing, or active) 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 (DD-MM-YYYY) Return data only from the specified date (e.g., 23-07-2020)
after Date (DD-MM-YYYY) Return data on or after the specified date (e.g., 23-07-2020)
before Date (DD-MM-YYYY) Return data on or before the specified date (e.g., 23-07-2020)
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.

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

Cumulative and daily totals for all data (cases, mortality, recovered, testing, and active cases) on a selected date or range of dates. By default returns province-level summaries for the most recent date in the dataset.

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 (DD-MM-YYYY) (default: the most recent date in the dataset) Return data only from the specified date (e.g., 23-07-2020)
after Date (DD-MM-YYYY) Return data on or after the specified date (e.g., 23-07-2020)
before Date (DD-MM-YYYY) Return data on or before the specified date (e.g., 23-07-2020)
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.

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" } ] }

Version

Date and time the dataset was last updated.

Parameters

No parameters for this query.

Sample query

https://api.opencovid.ca/version

Sample data returned Coming soon

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 Travellers RT 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