API

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

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)

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)

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

API

Navigation

Welcome

License

Acknowledgements

Issues, Suggestions and Code Availability

Basic Usage

Data types

Time Series Data

Parameters

Location

Sample queries

Summary

Parameters

Location

Sample query

Individual-level Data

Parameters

Location

Sample query

Supplementary Data (Other)

Parameters

Sample query

Version

Parameters

Sample query

Appendix

Notes

Two-letter province codes

Health region codes