Health Inequality Monitor

Health Inequality Monitor

Explore health inequality monitoring evidence, tools, resources and training

Health Inequality Data Repository: API Instructions

The Health Inequality Data Repository (HIDR) contains more than 50 datasets of disaggregated data covering diverse topics and dimensions of inequality from various publicly available data sources. The Application Programming Interface (API) offers users a systematic way to list and download the existing data and metadata files in the HIDR. An API call is the process of submitting a request to an API, and that API retrieving the requested data. The HIDR can either be queried using an OData API, or entire datasets or metadata documents can be downloaded using Swagger (OpenAPI). 

Citation

API users should add the following citation to any application, website, tool, or document that receives data from the Health Inequality Data Repository API:

The Health Inequality Data Repository API. Version 1.0. Geneva, World Health Organization, 2023. Available from https://www.who.int/data/inequality-monitor/data. [Accessed DD-MM-YYYY]

OData API

OData (Open Data Protocol) can be used to query the data in the Health Inequality Data Repository. The base OData feed URL is https://frontdoor-r5quteqglawbs.azurefd.net/HEM/ and specific dataset URLs are available in the OData feed URLs reference document above. More information about OData can be found here. 

Swagger API

The open-source ecosystem Swagger hosts the HIDR OpenAPI. This API provides two main functions (Download and Files) that leverage the HIDR folder structure. The Download function aims to facilitate the download of files for each dataset, while the Files function provides a list of the existing files in each dataset folder. Further details about the API’s offered functions and queries can be found in the Swagger HTML index. 

Query structure

The basic structure of queries comprises the base path, the function name, and the specific call (detailed in the endpoint path). Users must paste the full query structure to the address bar in an internet browser to execute the desired call successfully. Other software such as R or Stata can also download and manage the data using this basic structure. Code samples in R and Stata are available here: 

Example code in R

Example code in Stata

Base path: All URL queries have the base path https://datasafe-h5afbhf4gwctabaa.z01.azurefd.net/api/

Function name: Functions offered are Download or Files (see below for further detail).

Endpoint path: The endpoint includes the main group name (TOP), the dataset ID, and the specific call. Dataset IDs are located in the Dataset IDs reference table (see link above). Calls include requesting only the data (.xlsx) file (/data) or only the metadata (.pdf) file (/metadata). If /data or /metadata are not specified, a ZIP file containing both the data and metadata files will be downloaded. 

Download

The Download function offers three types of calls:

Download the latest version of both the data and metadata files

This call lets users download a ZIP file containing the latest data and metadata files for the dataset ID 'rep_rmnch':

https://datasafe-h5afbhf4gwctabaa.z01.azurefd.net/api/Download/TOP/rep_rmnch

Download the latest version of a data or a metadata file

These calls let users download the latest version of either a data or a metadata file for the dataset ID 'rep_rmnch':

https://datasafe-h5afbhf4gwctabaa.z01.azurefd.net/api/Download/TOP/rep_rmnch/data

https://datasafe-h5afbhf4gwctabaa.z01.azurefd.net/api/Download/TOP/rep_rmnch/metadata

Download a specific version of a data or metadata file

This call lets users download a specific version of a data or metadata file for the dataset ID 'rep_rmnch' by specifiying the version date in YYYY-MM-DD format:

https://datasafe-h5afbhf4gwctabaa.z01.azurefd.net/api/Download/TOP/rep_rmnch/2023-04-03/data

https://datasafe-h5afbhf4gwctabaa.z01.azurefd.net/api/Download/TOP/rep_rmnch/2023-04-03/metadata

Files

The Files function lists the existing files in the HIDR. This function has two types of calls, and API responses are returned in JSON format:

List the latest version of a dataset file

This call lists all existing files within the latest version of a data folder of a HIDR dataset, such as dataset ID 'rep_rmnch':

https://datasafe-h5afbhf4gwctabaa.z01.azurefd.net/api/Files/TOP/rep_rmnch/latest

List all files in a data folder

This call lists all existing files within a data folder of a HIDR dataset, such as dataset ID 'rep_rmnch':

https://datasafe-h5afbhf4gwctabaa.z01.azurefd.net/api/Files/TOP/rep_rmnch