Back to homepage

Get started

An open API from the University of Maryland

This is an API for accessing the daily COVID-19 World Symptoms Survey data. The details of our methodology, disclaimer, and release log can be checked here.
Data calculated based on the Facebook global symptoms survey data. Using the survey data, we estimate the percentage of people in a given country or region.

The base path. All URLs referenced in the documentation have the base path https://covidmap.umd.edu/api/

The endpoint path. For example, resources?indicator={indicator}&type={type}&country={country}&date={date}

Required parameters. These parameters must be included in a request. In the example above, {indicator}, {type}, {country}, and {date} are required. In a request, you will replace the placeholders with real values.

Optional parameters. These additional parameters can be included to customize a query to get regional aggregates, smoothed aggregates, all regions, etc.

EXAMPLE

https://covidmap.umd.edu/api/resources?indicator=covid&type=smoothed&country=italy&date=20201110


{"data": 
  [
      {
          "smoothed_cli": 0.008213,
          "smoothed_cli_se": 0.000709,
          "sample_size": 30879.0,
          "country": "Italy",
          "iso_code": "ITA",
          "gid_0": "ITA",
          "survey_date": "20201110"
      }
    ],
          "status": "success"
}

Notices and Updates

For updates, including data corrections, new aggregates, and any other changes to the API, we encourage you to subscribe to our COVID-19 API mailing list.

Date Notice
3/5/2021 New aggregate indicators for survey version 10 are available now. These include indicators for barrier reasons for why respondents don't think they need a COVID-19 vaccine, how informed respondents are about the COVID-19 vaccine, and indicators on vaccine appointment information.
Please refer to the survey instrument documentation for more information on the questions used for these indicators.
2/6/2021 New aggregate indicators for survey version 9 are available now. These include indicators for barrier reasons for vaccine acceptance from V5 question in survey version 9.
The trust_healthcare indicator will be discontinued as of 2/14/2021. As of 2/6/2021, the trust_doctors indicator is being be populated. Question V4_2, which was used for the trust_healthcare indicator, has been discontinued in survey version 9. Question V4_6 replaces question V4_2 in survey version 9. Question V4_6 is used in the trust_doctors indicator. Please refer to the survey documentation for more information on the question differences.
1/21/2021 We have implemented an updated definition for some of the aggregate indicators in the UMD Open Data API. This definition change impacts the following indicators: mask-wearing, financial worry, social distancing, and vaccine acceptance. We are implementing this change to make our estimates more directly comparable to those in Carnegie Mellon University Delphi research group’s COVIDcast API, which uses data from the US version of the COVID-19 Symptom Survey. Find a more detailed description under the release log section here.
12/6/2020 We released an update to our API. Before this update, the definition of COVID-like illness(CLI) and influenza-like illness (ILI) had been inadvertently switched in the API data. We have implemented a fix that corrects both historic and future data. Click here to read a detailed summary of the issue and fix.
This issue does not affect individual-level survey responses that are provided to entities who have signed a microdata use agreement. It also does not affect the US data which has been collected and distributed by Carnegie Mellon University. US estimates in the UMD and Facebook maps are also unaffected.

get survey aggregates

To get aggregates you need to make a call to the following url :
https://covidmap.umd.edu/api/resources?indicator={indicator}&type={type}&country={country}&date={date}


QUERY PARAMETERS

Parameter Description Example
indicator Aggregate data to query covid, mask, vaccine_acpt
type Aggregate data type to use daily or smoothed
country Country to query aggregates for Italy, Colombia, Australia
region Region to query aggregates for (optional) Piemonte, Santander, New South Wales
date Used to query aggregate data for a specific day 20210101
daterange Use to query aggregates data within a time range (optional) 20210101-20210115

The mandatory parameters here are indicator, type, country, and date.
Set country to all to retrieve data for all countries.
Set region to all to retrieve data for all regions for a specific country.
Set both country and region to all to retrieve all data.

Wildcard characters % and _ are enabled for country and region. See requests section for examples.
If you prefer to use iso_code , gid_0 and gid_1 , you can use our lookup table to convert country names or region names into the geocodes you prefer.
Note: the upper limit of returned records of a query is 3600. Users will receive a status message at the end of the JSON data saying, "data truncated when the upper limit is reached."


INDICATOR LIST

List of indicator aggregate data currently available:

Indicator Description Survey Question
covid Respondents that have reported COVID-like illness (CLI). COVID-like illness: fever, along with cough, shortness of breath, or difficulty breathing. B1_1, B1_2, B1_3
flu Respondents that have reported Influenza-like illness (ILI). Influenza-like illness: fever, along with cough or sore throat. B1_1, B1_2, B1_7
mask Respondents who wore a mask all the time or most of the time when in public. C5
contact Respondents that have reported having had direct contact (longer than 1 minute) with people not staying with them. C1_m
finance Respondents who are very worried or somewhat worried about themselves and their household's finances. D5
anosmia Respondents reporting anosmia (loss of smell or taste). B1_10
vaccine_acpt Respondents definitely or probably choosing to get vaccinated if a COVID-19 vaccine was offered to them. V3
covid_vaccine Respondents vaccinated with a COVID-19 vaccine. V1
trust_fam Respondents more likely to get vaccinated if recommended by friends and family. V4_1
trust_healthcare Respondents more likely to get vaccinated if recommended by local healthcare workers. Note: no longer being populated. It has been replaced by trust_doctors. V4_2
trust_who Respondents more likely to get vaccinated if recommended by the WHO. V4_3
trust_govt Respondents more likely to get vaccinated if recommended by government health officials. V4_4
trust_politicians Respondents more likely to get vaccinated if recommended by politicians. V4_5
twodoses Respondents having received 2 doses of a COVID-19 vaccine. V2
concerned_sideeffects Respondents being very or moderately concerned about COVID-19 vaccine side effects. V9
hesitant_sideeffects Respondents very or moderately concerned about COVID-19 vaccine side effects, conditional on being hesitant (would NOT choose to get vaccinated if offered a vaccine). V3, V9
modified_acceptance Respondents that are vaccine accepting where people who are vaccinated are included as accepting. V1, V3
access_wash Respondents with access to soap and water for washing their hands. C8
wash_hands_24h_3to6 Respondents who washed their hands 3 to 6 times in the last 24 hours. C7
wash_hands_24h_7orMore Respondents who washed their hands 7+ times in the last 24 hours. C7
cmty_covid Respondents who personally know anyone in their local community who is sick with a fever and either a cough or difficulty breathing. B3
barrier_reason_side_effects Respondents who are concerned about possible side effects of a COVID-19 vaccine. V5a_1,V5b_1,V5c_1
barrier_reason_wontwork Respondents who don’t know if a COVID-19 vaccine will work. V5a_2,V5b_2,V5c_2
barrier_reason_dontbelieve Respondents who don’t believe they need a COVID-19 vaccine. V5a_3,V5b_3,V5c_3
barrier_reason_dontlike Respondents who don’t like vaccines. V5a_4,V5b_4,V5c_4
barrier_reason_waitlater Respondents who plan to wait and see if the vaccine is safe and may get it later. V5a_5,V5b_5,V5c_5
barrier_reason_otherpeople Respondents who think other people need the vaccine more than they do right now. V5a_6,V5b_6,V5c_6
barrier_reason_cost Respondents who are concerned about the cost of a COVID-19 vaccine. V5a_7,V5b_7,V5c_7
barrier_reason_religious Respondents whose religious beliefs are against vaccination. V5a_8,V5b_8,V5c_8
barrier_reason_other Respondents who have other reasons not to get a COVID-19 vaccine. V5a_9,V5b_9,V5c_9
trust_doctors Respondents more likely to get vaccinated if recommended by doctors and other health professionals they go to for medical care. V4_6
barrier_reason_dontneed_alreadyhad Respondents who do not believe they need a COVID-19 vaccine because they already had the COVID-19 virus. V6_1,V1
barrier_reason_dontneed_dontspendtime Respondents who do not believe they need a COVID-19 vaccine because they do not spend time with any high-risk people. V6_2,V1
barrier_reason_dontneed_nothighrisk Respondents who do not believe they need a COVID-19 vaccine because they are not part of a high-risk group. V6_3,V1
barrier_reason_dontneed_takeprecautions Respondents who do not believe they need a COVID-19 vaccine because they plan to use masks or other precautions instead. V6_4,V1
barrier_reason_dontneed_notserious Respondents who do not believe they need a COVID-19 vaccine because they do not belive COVID-19 is a seuorus illeness. V6_5,V1
barrier_reason_dontneed_notbeneficial Respondents who do not believe they need a COVID-19 vaccine because they do not think vaccines are beneficial. V6_6,V1
barrier_reason_dontneed_other Respondents who do not believe they need a COVID-19 vaccine because of other reasons which are not not listed. V6_7,V1
informed_access Respondents who reported being very informed or moderately informed about how to be able to get a COVID-19 vaccine. V13
appointment_have Respondents who reported having an appointment to receive a COVID-19 vaccine. V15
appointment_tried Respondents who reported having tried to get an appointment to receive a COVID-19 vaccine. V16

DATA FIELDS

Data fields returned form an API query:

Field Description
country Country name.
region Sub-country region name. Generally, it is at the state or province-level or equivalent.
pct_* Weighted percentage of respondents that have reported the specified indicator, where * is the indicator, except for the following indicators:
covid, where * = cli
flu, where * = ili
mask, where * = mc
contact, where * = dc
finance, where * = hf
anosmia, where * = anos
vaccine_acpt, where * = vu
pct_*_unw Unweighted percentage of respondents that have reported the specified indicator, where * is the indicator, except for the following indicators:
covid, where * = cli
flu, where * = ili
mask, where * = mc
contact, where * = dc
finance, where * = hf
anosmia, where * = anos
vaccine_acpt, where * = vu
smoothed_* Seven-day rolling average of pct_*
*_se Standard error of pct_*
*_se_unw Standard error of pct_*_unw
smoothed_*_se Standard error of smoothed_*
sample_size_* Sample size for calculating the targeted indicator value.
iso_code The ISO country codes are internationally recognized codes that designate every country and most of the dependent areas a two-letter or three-letter combination.
gid_0 The code for join country level data to the GADM country-level data (click to download).
gid_1 The code for join region-level data to the GADM region-level data (click to download).

GET SURVEY COUNTS

To get Part-A and Full survey response counts you need to make a call to the following URL:
https://covidmap.umd.edu/api/counts?date={date}

EXAMPLE

https://covidmap.umd.edu/api/counts?date=20210109


{"data": 
  [
      {
          "parta_responses": 162051.0,
          "full_responses": 160432.0,
          "survey_date": "20210109"
      }
    ],
          "status": "success"
}

Requests

Method: GET

Retrieve the country list or region list for survey responses

Country list:

https://covidmap.umd.edu/api/country


{"data": 
  [
      {
          "country": "Afghanistan"
      },
      {
          "country": "Albania"
      },
      ...
    ]
}


Region list:

https://covidmap.umd.edu/api/region


{"data": 
  [
      {
          "country": "Angola",
          "region": "Luanda"
      },
      {
          "country": "Argentina"
          "region": "Buenos Aires"
      },
      ...
    ]
}


Retrieve all dates for survey responses for a place

Country:

https://covidmap.umd.edu/api/datesavail?country={country}

Example for https://covidmap.umd.edu/api/datesavail?country=France


{"data": 
  [
      {
          "country": "France",
          "survey_date": "20200423"
      },
      {
          "country": "France",
          "survey_date": "20200424"
      },
      ...
    ]
}


Region:

https://covidmap.umd.edu/api/datesavail?country={country}&region={region}

Example for https://covidmap.umd.edu/api/datesavail?country=Angola&region=Luanda


{"data": 
  [
      {
          "country": "Angola",
          "region": "Luanda",
          "survey_date": "20200503"
      },
      {
          "country": "Angola",
          "region": "Luanda",
          "survey_date": "20200504"
      },
      ...
    ]
}


Retrieve data using Wildcard characters

Using %:

The following will return all the dates for survey responses for any countries whose name starts with United

https://covidmap.umd.edu/api/datesavail?country=United%


{"data": 
  [
      {
          "country": "United Arab Emirates",
          "survey_date": "20200423"
      },
      {
          "country": "United Arab Emirates",
          "survey_date": "20200424"
      },
      ...
      {
          "country": "United Kingdom",
          "survey_date": "20200423"
      },
      {
          "country": "United Kingdom",
          "survey_date": "20200424"
      },
      ...
    ]
    "status": "success"
}


Using _:

The following will return all the dates for survey responses for any countries with a six-character name where the first three characters are g, r, e and the last two characters are c, e.

https://covidmap.umd.edu/api/datesavail?country=gre_ce


{"data": 
  [
      {
          "country": "Greece",
          "survey_date": "20200423"
      },
      {
          "country": "Greece",
          "survey_date": "20200424"
      },
      ...
      {
          "country": "Greece",
          "survey_date": "20200425"
      },
      ...
    ]
    "status": "success"
}


Retrieve data for a particular indicator

Country:

Specify the indicator, the type, the country, and a date or date range.

The following will return daily data for the mask indicator for the country of Germany from 9/21/2020 to 10/6/2020.

https://covidmap.umd.edu/api/resources?indicator=mask&type=daily&country=Germany&daterange=20200921-20201006


{"data": 
  [
      {
          "percent_mc": 0.801253,
          "mc_se": 0.007164
          "percent_mc_unw": 0.805101
          "mc_se_unw": 0.007218
          "sample_size": 3058.0
          "country": "Germany"
          "iso_code": "DEU"
          "gid_0": "DEU"
          "survey_date": "20200921"
      },
      ...
      {
          "percent_mc": 0.83902,
          "mc_se": 0.006351
          "percent_mc_unw": 0.83824
          "mc_se_unw": 0.006338
          "sample_size": 3363.0
          "country": "Germany"
          "iso_code": "DEU"
          "gid_0": "DEU"
          "survey_date": "20201006"
      },
    ]
    "status": "success"
}


Region:

Specify the indicator, the type, the country, the region, and a date or date range.

The following will return daily data for the covid indicator for Saint Petersburg, Russia from 1/1/2021 to 1/6/2021.

https://covidmap.umd.edu/api/resources?indicator=covid&type=daily&country=Russia&region=Saint%20Petersburg&daterange=20210101-20210106


{"data": 
  [
      {
          "percent_cli": 0.055563,
          "cli_se": 0.027017,
          "percent_cli_unw": 0.058442,
          "cli_se_unw": 0.018903,
          "sample_size": 154.0,
          "country": "Russia",
          "region": "Saint Petersburg",
          "iso_code": "RUS",
          "gid_0": "RUS",
          "gid_1": "RUS.14_1",
          "survey_date": 20210101
      },
      ...
      {
          "percent_cli": 0.016442,
          "cli_se": 0.014596,
          "percent_cli_unw": 0.01676,
          "cli_se_unw": 0.009595,
          "sample_size": 179.0,
          "country": "Russia",
          "region": "Saint Petersburg",
          "iso_code": "RUS",
          "gid_0": "RUS",
          "gid_1": "RUS.14_1",
          "survey_date": "20210106"
      },
    ]
    "status": "success"

}

Set country to all to retrieve all the country data for a specified indicator.
Set region to all to retrieve all the regional data for a specified indicator.
Set type to smoothed to retrieve smoothed aggregates.

Method: Python

Example showing how to use this API in Python


import requests
import json
# request data from api
response = requests.get("https://covidmap.umd.edu/api/resources?indicator=covid&type=smoothed&country=Afghanistan&daterange=20200424-20200426").text

#convert json data to dic data for use!
jsonData = json.loads(response)


Method: R

Example showing how to use this API in R


library(tidyverse)
library(httr)
library(jsonlite)

# adding url
path <- "https://covidmap.umd.edu/api/resources?indicator=covid&type=smoothed&country=Afghanistan&daterange=20200424-20200426"

# request data from api
request <- GET(url = path)

# make sure the content is encoded with 'UTF-8'
response <- content(request, as = "text", encoding = "UTF-8")

# now we can have a dataframe for use!
coviddata <- fromJSON(response, flatten = TRUE) %>% data.frame()

Citing

We hope this API is useful to different research groups. If you use the API and would like to cite it, the following represents a proper citation of the API itself:

Junchuan Fan, Yao Li, Kathleen Stewart, Anil R. Kommareddy, Adrianne Bradford, Samantha Chiu, Frauke Kreuter, Neta Barkay, Alyssa Bilinski, Brian Kim, Roee Eliat, Tal Galili, Daniel Haimovich, Sarah LaRocca, Stanley Presser, Katherine Morris, Joshua A Salomon, Elizabeth A. Stuart, Ryan Tibshirani, Tali Alterman Barash, Curtiss Cobb, Andres Garcia, Andi Gros, Ahmed Isa, Alex Kaess, Faisal Karim, Ofir Eretz Kedosha, Shelly Matskel, Roee Melamed, Amey Patankar, Irit Rutenberg, Tal Salmona, David Vannette (2020). COVID-19 World Symptom Survey Data API. https://covidmap.umd.edu/api.html