API

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

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

API

Navigation

Welcome

License

Acknowledgements

Code availability

Basic Usage

Data types

Individual-level Data

Parameters

Location

Sample query

Time Series Data

Parameters

Location

Sample queries

Summary

Parameters

Location

Sample query

Version

Parameters

Sample query

Appendix

Notes

Two-letter province codes

Health region codes