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

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 8 variables of data which will be found within a row (associated key name in brackets):

• Cases (cases)
• Deaths (deaths)
• Tests (tests)
• Hospitalizations (hosp)
• ICU admissions (icu)
• Healthcare workers infected (healthcare)
• Vaccinations 1st dose (vac1)
• Vaccinations 2nd dose (vac2)

Within these variables we have a standardised group of values that each variable contains (associated key suffix in brackets):

• Date of data retrieval (_date)
• Total (_total) - not in tests
• Total sum of sex-disaggregated (_total_sum) - only in cases and deaths
• Male Count (_male)
• Female Count (_female)
• Male Percent (_male_pct)
• Female Percent (_female_pct)

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.

["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"
        ...
      }
    ...
  }

["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):

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:

About

Our Age-Sex Data source contains twice-monthly updated values of age and sex-disaggregated data specifically for cases, deaths, and vaccinations, 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 or only vaccinations, and many countries report none and so will not show within the data. There is no guarantee that a country will use the same age ranges for both cases, deaths, or vaccinations, 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, Austria is reporting cases, deaths, and vaccinations, but many countries will not report all of these, and may contain different age ranges if they do.

["data"] =>
  array {
    ["Austria"] =>
      array {
        ["CasebyAgeSex"] =>
          array {
            [0] =>
              array {
                ["country"]     => "Austria"
                ["date"]        => "4/21/21"
                ["age_group"]   => "0-4"
                ...
              }
            [1] =>
              array {
                ["country"]     => "Austria"
                ["date"]        => "4/21/21"
                ["age_group"]   => "5-14"
                ...
              }
            [2] =>
              array {
                ["country"]     => "Austria"
                ["date"]        => "4/21/21"
                ["age_group"]   => "15-24"
                ...
              }
            ...
          }
		["DeathsbyAgeSex"] =>
          array {
            [0] =>
              array {
	            ["country"]=> "Austria"
                ["date"]=> "4/21/21"
                ["age_group"]=> "0-4"
                ...
              }
            [1] =>
              array {
	            ["country"]=> "Austria"
                ["date"]=> "4/21/21"
                ["age_group"]=> "5-14"
                ...
              }
            [2] =>
              array {
	            ["country"]=> "Austria"
                ["date"]=> "4/21/21"
                ["age_group"]=> "15-24"
                ...
              }
            ...
          }
		["VacsbyAgeSex"] =>
          array {
            [0] =>
              array {
	            ["country"]=> "Austria"
                ["date"]=> "4/18/21"
                ["age_group"]=> "0-24"
                ...
              }
            [1] =>
              array {
	            ["country"]=> "Austria"
                ["date"]=> "4/18/21"
                ["age_group"]=> "25-34"
                ...
              }
            [2] =>
              array {
	            ["country"]=> "Austria"
                ["date"]=> "4/18/21"
                ["age_group"]=> "35-44"
                ...
              }
            ...
          }
      }
  }

Response Values

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

You should check to see if the above keys exist; if a country does not report either cases, deaths, or vaccinations 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 data for an age group.

For CasebyAgeSex and DeathsbyAgeSex the arrays will contain the below key/values.

For VacsbyAgeSex the arrays will contain the below key/values.

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:

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:

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.

v1.1

Summary data

• Vaccination data added to Summary Data
• Vaccination 1st dose (vac1) added as variable
• Vaccination 2nd dose (vac2) added as variable
• fullvars data parameter will include vac1 and vac2 data
• Vaccination keys added to Response Values
• Multiple Response Values keys have been depracated in order to normalise key structure to variable name + data type suffix. These keys are still in use but may be removed in a future version.

Age-Sex Data

• Vaccination data added to Age-Sex Data
• Response Format updated to display vaccination structure
• Vaccination keys added to Response Values (some differences to cases and deaths)
• data parameter updated to accomodate vaccination data and can accept multiple values

Error Codes

• New error code 2002; occurs when the code parameter is used but does not match any country in the data