COVID-19 World Survey Data API

An open API from the University of Maryland

About

This is an API for accessing the daily global Facebook symptoms survey data. The details of our methodology and disclaimer can be checked here.

Data fields

There are seven fields in the dataset. Detailed descriptions are listed below:

Parameters for API query

There are five parameters used for query,indicator, type, country, region, date and daterange. The mandatory fields here are indicator , type and country. Users still need to specify at least one value for date and daterange. Users can also set country or region values to all to retrieve the data for all the countries or all regions from a country or all the regions from all countries. Wildcard characters % and _ are enabled for country and region . % sign represents zero, one or more characters while _ sign represents one character. 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 reach the upper limit.

ParametersDescriptionFormat
indicatorspecify which data to usee.g. covid or flu
typespecify the data type to usee.g. daily or smoothed
countryuse to query data for a countrystring
regionuse to query data for a regionstring
dateuse to query data for a specific daye.g.20200424
daterangeuse to query data within a time rangee.g.20200424-20200430

 

Request

Method: GET

Step 1. Retrieve the country list or region list for survey responses, use link: https://covidmap.umd.edu/api/country or https://covidmap.umd.edu/api/region

For example, using the link https://covidmap.umd.edu/api/country should return the response:

Using the link https://covidmap.umd.edu/api/region should return the response:

Step 2. To retrieve all the dates for survey responses for a place (country or region), use link: https://covidmap.umd.edu/api/datesavail?country=<country> or https://covidmap.umd.edu/api/datesavail?country=<country>&region=<region>

For example, using the link https://covidmap.umd.edu/api/datesavail?country=Afghanistan The response will be all the dates for survey responses for Afghanistan :

Using the link https://covidmap.umd.edu/api/datesavail?country=Angola&region=Luanda The response will be all the dates for survey responses for the region Luandain Angola :

Using the link https://covidmap.umd.edu/api/datesavail?country=United% The response will be all the dates for survey responses for any courntries with the country name started with United:

Using the link https://covidmap.umd.edu/api/datesavail?country=gre_ce The response will be all the dates for survey responses for any countries have a six-character name and the first three characters areg,r,eand the last two characters in the name are c, e:

Step 3. To extract data for a country for a particular date use: https://covidmap.umd.edu/api/resources?indicator=<indicator>&type=<type>&country=<country>&date=<YYYYMMDD> To extract data for a region in a country for a particular date use: https://covidmap.umd.edu/api/resources?indicator=<indicator>&type=<type>&country=<country>&region=<region>&date=<YYYYMMDD> Or to extract data for a region within a time range use: https://covidmap.umd.edu/api/resources?indicator=<indicator>&type=<type>&country=<country>&region=<region>&daterange=<YYYYMMDD-YYYYMMDD>

For example, when using https://covidmap.umd.edu/api/resources?indicator=covid&type=daily&country=Afghanistan&daterange=20200424-20200426, The response will be all the daily COVID-like illness (CLI) related data between 20200424 to 20200426 for Afghanistan :

Using https://covidmap.umd.edu/api/resources?indicator=covid&type=daily&country=Greece&region=all&date=20200504 to retrieve the daily CLI related data for all regions in Greece for 20200504. The response will be:

Note the maximum number returned records for an api query is 3600, and the user is recommended to refine the geographic and time range of a query.

Method: Python

Method: R