API v1 Documentation

Last modified: 1st September 2020

Introduction

Global Health 50/50 (GH5050) continuously analyses the official data on Covid-19 provided by individual countries and utilises this data for our online data report pages. These reports can be found by searching our main website:

https://globalhealth5050.org/

GH5050 focuses on sex-disaggregated data; male and female data reported separately. We do not have data on every country in the world, and many countries provide no or only partial sex-disaggregated data.

GH5050 API v1 provides access to two data sources; what they contain and how they can be accessed can be found on the page you are currently viewing. The link for the documentation of the api version you are currently viewing is:

https://api.globalhealth5050.org/docs/v1

Summary Data

About

Our Summary Data source contains twice-monthly updated values of sex-disaggregated data for every country that we report on, e.g. the amount of males and females who have been confirmed to have had Covid-19 in that particular country. Countries will have multiple rows of data when being tracked over time; the various date values in a row will show when that data was collected.

To access this source you can use the following link:

https://api.globalhealth5050.org/api/v1/summary

Variables

Our data focuses on 6 variables of data which will be found within a row:

  • Cases
  • Deaths
  • Tests
  • Hospitalizations
  • ICU admissions
  • Healthcare workers infected

Within these variables we have a standardised group of values that each variable contains:

  • Date of data retrieval
  • Total (not in tests)
  • Total sum of sex-disaggregated (only in cases and deaths)
  • Male Count
  • Female Count
  • Male Percent
  • Female Percent

Response Format

Our API outputs a string containing a JSON-encoded multi-dimensional array of data, wrapped in the data key. If there is an error with your request, the data key will be empty or not set, and an error key containing the error response will be returned instead. The two structures our data can take when returning a valid response, dependant on whether historical data is included or not, are displayed below.

Two dimensional array - fullcd, fullvars, latest 'data' parameter

["data"] =>
  array {
    ["Afghanistan"] =>
      array {
        ["country"]           => "Afghanistan"
        ["country_code"]      => "AF"
        ["date"]              => "7/7/2020"
        ["sexdisagg_data"]    => "Yes"
        ...
      }
    ["Albania"] =>
      array {
        ["country"]           => "Albania"
        ["country_code"]      => "AL"
        ["date"]              => "7/6/2020"
        ["sexdisagg_data"]    => "Yes"
        ...
      }
    ...
  }

Three dimensional array - historic 'data' parameter (historical data is included)

["data"] =>
  array {
    ["Afghanistan"]=>
      array {
        [0] =>
          array {
            ["country"]           => "Afghanistan"
            ["country_code"]      => "AF"
            ["date"]              => "6/23/2020"
            ["sexdisagg_data"]    => "Yes"
            ...
          }
        [1] =>
          array {
            ["country"]           => "Afghanistan"
            ["country_code"]      => "AF"
            ["date"]              => "7/7/2020"
            ["sexdisagg_data"]    => "Yes"
            ...
          }
          ...
      }
    ["Albania"] =>
      array {
        [0] =>
          array {
            ["country"]           => "Albania"
            ["country_code"]      => "AL"
            ["date"]              => "6/8/2020"
            ["sexdisagg_data"]    => "Yes"
            ...
          }
        [1] =>
          array {
            ["country"]           => "Albania"
            ["country_code"]      => "AL"
            ["date"]              => "6/22/2020"
            ["sexdisagg_data"]    => "Yes"
            ...
          }
        ...
      }
    ...
  }

Response Values

The return data keys and values can be found below (Afghanistan is used as an example of the data that may be returned):

Key Expected Value Description
country string
Afghanistan
Name of country
country_code string
AF
2 letter country code from ISO, used by WHO
date date (M/D/YYYY)
6/23/2020
Date of data check
sexdisagg_data Yes/No/Partial
Yes
Is the country reporting sex-disaggregated data for cases and deaths?
date_tests date (M/D/YYYY) or empty
empty
Date for testing data
tests_male int or empty
empty
Number of covid-19 tests administered to males (reported)
tests_female int or empty
empty
Number of covid-19 tests administerd to females (reported)
tests_male_pct float or empty
empty
Percent of reported tests administerd to males
tests_female_pct float or empty
empty
Percent of reported tests administerd to females
date_cases date (M/D/YYYY) or empty
6/23/2020
Date for case data
cases_total int or empty
29481
Total number of confirmed cases of covid-19
cases_total_sum int or empty
25987
Sum of sex-disaggregated cases reported
cases_male int or empty
18847
Number of confirmed cases of covid-19 among males
cases_female int or empty
7140
Number of confirmed cases of covid-19 among females
cases_male_pct float or empty
0.725247239
Percent of sex-disaggregated confirmed cases of covid-19 among males
cases_female_pct float or empty
0.274752761
Percent of sex-disaggregated confirmed cases of covid-19 among females
date_deaths date (M/D/YYYY) or empty
6/23/2020
Date for death data
deaths_total int or empty
618
Total number of deaths due to covid-19
deaths_total_sum int or empty
423
Sum of sex-disaggregated deaths reported
deaths_male int or empty
336
Number of covid-19 deaths to males
deaths_female int or empty
87
Number of covid-19 deaths to females
deaths_male_pct float or empty
0.794326241
Percent of sex-disaggregated covid-19 deaths that were to males
deaths_female_pct float or empty
0.205673759
Percent of sex-disaggregated covid-19 deaths that were to females
hosp_date date (M/D/YYYY) or empty
6/24/2020
Date of data for covid-19 hospitalizations
hosp_total int or empty
2645
Total number of covid-19 hospitalizations
hosp_male int or empty
1946
Number of males hospitalized for covid-19
hosp_female int or empty
699
Number of females hospitalized for covid-19
hosp_male_pct float or empty
0.735727788
Percent of total sex-disaggregated hospitalizations who were male
hosp_female_pct float or empty
0.264272212
Percent of total sex-disaggregated hospitalizations who were female
icu_date date (M/D/YYYY) or empty
empty
Date for ICU admissions data
icu_total int or empty
empty
Total ICU admissions for covid-19
icu_male int or empty
empty
Number of males admitted to ICU for covid-19
icu_female int or empty
empty
Number of females admitted to ICU for covid-19
icu_male_pct float or empty
empty
Percent of ICU admissions who were male
icu_female_pct float or empty
empty
Percent of ICU admissions who were female
date_healthcare date (M/D/YYYY) or empty
empty
Date for Healthcare Worker data
healthcare_tot int or empty
empty
Total number of healthcare workers infected with covid-19
healthcare_male int or empty
empty
Number of male healthcare workers infected with covid-19
healthcare_female int or empty
empty
Number of female healthcare workers infected with covid-19
healthcare_male_pct float or empty
empty
Percent of healthcare workers infected with covid-19 who are male
healthcare_female_pct float or empty
empty
Percent of healthcare workers infected with covid-19 who are female
date_cfr date (M/D/YYYY) or empty
6/23/2020
Date of mortality data
cfr_pct_tot float or empty
0.016277
Proportion of all confirmed cases that have died (both sexes)
cfr_pct_male float or empty
0.017828
Proportion of confirmed cases that have died (male)
cfr_pct_female float or empty
0.012185
Proportion of confirmed cases that have died (female)
cfr_ratio float or empty
1.463107
Ratio of confirmed cases that have died M:F
totpop2020 float
38928.00
Total population in 1000s
malepop2020 float
19976.00
Male population in 1000s
femalepop2020 float
18952.00
Female population in 1000s

Parameters

The data that is returned by the API can be tailored to your needs by appending GET variables to the URL. Below you can find the available GET variables and what they do:

GET key Accepted Values Default
code 2 letter string Returns row(s) of the country which has the provided 2 letter ISO country code. Multiple values can be matched by separating with a comma, e.g. ?code=AF,AL will match Afghanistan and Albania. none
data fullcd Will search all rows for each country to return a result where both cases and deaths contain data on the same date, even if historical. fullcd
fullvars Will search all rows for each country to return a result where each variable (see 'Variables' for more information) contains data, even if historical or from different dates/rows.
historic Returns all rows of data for each country, including latest row, in three-dimensional array.
latest Returns most recently added row of data for each country.

Age-Sex Data

About

Our Age-Sex Data source contains twice-monthly updated values of age and sex-disaggregated data specifically for cases and deaths, e.g. the amount of males and females with an age range who have been confirmed to have had Covid-19 in that particular country. This source contains only our most recent findings and does not contain historical records. Some countries may only report cases or only deaths, and many countries report neither and so will not show within the data. There is no guarantee that a country will use the same age ranges for both cases and deaths, and no normalisation has occured across countries' age ranges.

To access this source you can use the following link:

https://api.globalhealth5050.org/api/v1/agesex

Response Format

Our API outputs a string containing a JSON-encoded multi-dimensional array of data, wrapped in the data key. If there is an error with your request, the data key will be empty or not set, and an error key containing the error response will be returned instead. In the example below, Afghanistan is reporting both cases and deaths, but many countries will not report both, and may contain different age ranges if they do.

["data"] =>
  array {
    ["Afghanistan"] =>
      array {
        ["CasebyAgeSex"] =>
          array {
            [0] =>
              array {
                ["country"]     => "Afghanistan"
                ["date"]        => "8/4/20"
                ["age_group"]   => "0-9"
                ...
              }
            [1] =>
              array {
                ["country"]     => "Afghanistan"
                ["date"]        => "8/4/20"
                ["age_group"]   => "10-19"
                ...
              }
            [2] =>
              array {
                ["country"]     => "Afghanistan"
                ["date"]        => "8/4/20"
                ["age_group"]   => "20-29"
                ...
              }
            ...
          }
		["DeathsbyAgeSex"] =>
          array {
            [0] =>
              array {
	            ["country"]=> "Afghanistan"
                ["date"]=> "8/4/20"
                ["age_group"]=> "0-9"
                ...
              }
            [1] =>
              array {
	            ["country"]=> "Afghanistan"
                ["date"]=> "8/4/20"
                ["age_group"]=> "10-19"
                ...
              }
            [2] =>
              array {
	            ["country"]=> "Afghanistan"
                ["date"]=> "8/4/20"
                ["age_group"]=> "20-29"
                ...
              }
            ...
          }
      }
  }

Response Values

The return data keys and values can be found below (Afghanistan cases is used as an example of the data that may be returned):

Parent Key Expected Value Description
CasebyAgeSex array or undefined Numeric array containing arrays of age ranges and male/female cases
DeathsbyAgeSex array or undefined Numeric array containing arrays of age ranges and male/female deaths

You should check to see if the above keys exist; if a country does not report either cases or deaths that key will not exist. If it does, inside you will find a numeric array ordered by age ascending each containing an array of the below key/values.

Key Expected Value Description
country string
Afghanistan
Name of country
date date (M/D/YY)
8/4/20
Date of data retreival
age_group string
0-9
Age range as a string, each country will have chosen their own age ranges and we do not standardise these.
age_begin int
0
Number containing the starting age of the age range
age_end int
9
Number containing the ending age of the age range
casesF/deathsF int
79/0
If viewing CasebyAgeSex this will be casesF and contain the cases for females in that age group.
If viewing DeathsbyAgeSex this will be deathsF and contain the deaths for females in that age group.
casesM/deathsM int
102/2
If viewing CasebyAgeSex this will be casesM and contain the cases for males in that age group.
If viewing DeathsbyAgeSex this will be deathsM and contain the deaths for males in that age group.
populationin1000sF float
5406.696
Population of females in the age group by 1000s
populationin1000sM float
5682.036
Population of males in the age group by 1000s

Parameters

The data that is returned by the API can be tailored to your needs by appending GET variables to the URL. Below you can find the available GET variables and what they do:

GET key Accepted Values Default
code 2 letter string Returns row(s) of the country which has the provided 2 letter ISO country code. Multiple values can be matched by separating with a comma, e.g. ?code=AF,AL will match Afghanistan and Albania. none
data both Returns both cases and deaths data where available. both
cases Returns only cases data and associated countries.
deaths Returns only deaths data and associated countries.

Error Response

Error Format

If there is an error with your request, an error key containing the error response will be returned, the structures of which is displayed below.

["error"] =>
  array {
    ["Code"]        => "1001"
    ["Details"]     => "Invalid API version"
    ["Docs"]        => "https://api.globalhealth5050.org/docs"
  }

Error Codes

Below you can find all error codes, why they happen, and how you can resolve them.

Many mistakes can happen because of a malformed URL, the correct format is:

https://api.globalhealth5050.org/api/API-VERSION/DATA-TYPE https://api.globalhealth5050.org/api/API-VERSION/DATA-TYPE?OPTIONAL_PARAM=VALUE&OPTIONAL_PARAM2=VALUE2...

 

Error Codes Description
0000 Unrecognised error, please read the error details for more information. If this error is not resolvable, please get in touch with the GH5050 team.
1001 'API version not chosen'. Request URL is malformed, make sure it is in the correct structure. /API-VERSION/DATA-TYPE is missing.
1002 'Incorrect API version'. Request URL is in correct structure, but API version does not exist. Make sure API-VERSION is correct.
1003 'No data type chosen'. Request URL is malformed, version is correct (API-VERSION), but missing DATA-TYPE section.
1004 'Incorrect data type'. Request URL is in correct structure, but data type does no exist. Please read through documentation to decide which data source you are requesting.
2001 'Data parameter does not match available options'. View the relevant Parameters section for the data format you are trying to fetch, and use one of the available options for the data key.
9001 'Hourly quota exceeded'. We provide 3,600 requests per each hour of the day, and this has been exceeded. You will have to wait until the next hour of the day to make a request.

Terms Of Use

When using our services, please avoid doing the following:

  • Abuse or misuse the API
  • Misuse GH5050 trademarks
  • Imply any sponsorship or association with GH5050
  • Misrepresent GH505 services as your own
  • Serve the data in its raw format
  • Sell the API service or data
  • Use techniques to bypass our rate limits
  • Automate mining of our data when not in use
  • Expect any guarantees about the accuracy of the data
  • Hold us liable if our service is unavailable

Rate Limit

Each request to the API consumes one available request from your quota. When an app hits the quota limit, subsequent requests are rejected with an error response until the hour is up.

The limit is 3,600 requests per hour.