The WHO/Europe Data Warehouse API is used to provide software developers programmatic access to the contents of the Data Warehouse at the WHO Regional Office for Europe. The API can be used to find recently added data sets, to search the Data Warehouse, to download the contents of the Data Warehouse for analysis, or to search for indicators and data sets related by common topic.
The general structure of the data model is as follows:
1. A "measure" is a collection of data for a particular indicator or another measurable concept. Most simply, one can think of a measure as containing values for a set of countries for an "indicator" or a "response to survey question". A measure has a set of metadata and attributes that describe it (unit type, measure type, etc).
2. Each measure has "notes", which describe the measure's definition, and also any country-specific notes that explain specifics of a particular country's values.
3. A list of measures can be combined into a "data set". A data set also has a set of metadata and attributes that describe it (data set owner, etc).
4. Measures of related topics are related to each other also according to topical "classifications", which can be used to programmatically query measures that may not belong to the same data set, but are related by a topic.
This specification describes version 3.8.4 of the API, and has the following sections:
- Data Warehouse (DW) is a central repository of health data from multiple data sources.
- API - Application Programming Interface (API) defines a way through which it is possible to programmatically interact with data stored in the Data Warehouse. WHO Europe API uses HTTP as a transport protocol and JSON (CSV) format for a response object.
- CSV - Comma-separated values (CSV) is a format that uses plain text to represent tabular data using rows and columns that are separated by commas.
- Metadata defines WHO Europe Data Warehouse data structure including Measures, Attributes, Measure-Attribute Codes, Fact-Attribute Codes and Notes. It can also be downloaded as a full Excel file (/api/v3/export_metadata), or as an individual measure metadata set, in the Excel download format.
- Measure is a set of facts with unique code and bilingual name that are defining an indicator. It most often corresponds to an indicator.
- Fact is a set of attribute codes that describe a value. Facts are collected into a measure.
- Attribute describes a measure or fact.
- Fact attributes describe dimensions of a measure (for example, YEAR, SEX, VACCINATIONSTATUS).
- Measure attributes describe the measure (EXTERNID, DATA_SOURCE, UNIT_TYPE). For example: DATA_SOURCE is measure attribute that defines where the data comes from. EXTERNID is the identifier of the indicator in the originating data source (if available).
- COUNTRY_GROUP is an attribute that represents a group of countries for which average values are available. Which countries belong to a particular country group is defined by relationships of countries-to-country groups. An example of a country group is WHO_EURO which depicts 53 countries of the WHO European Region, while CARINFONET describes countries that are members of the Central Asian Republics Information Network.
- COUNTRY is an attribute that represents a country or in exceptional circumstances, a subnational level of a country.
- Data set is set of measures that are combined into a coherent analyzable data set. The data set is most often a collection of indicators from a database, a data collection, a monitoring framework or an analytical publication. One measure (indicator) may belong to multiple data sets in the Data Warehouse.
- Note is a text field that describes a data set (data set note) or a measure (measure note; containing definition of an indicator). Moreover, explore country-measure notes for any country-level footnotes describing specifics of the measure's data for a particular country. Use the notes to understand the source and specifics of the data set or measure.
- Classification - in the context of the Data Warehouse, a classification is a make-shift "table of contents" that is assigned to a set of measures. All measures belonging to a particular term in the classification are related by that topic/theme. A classification hierarchy may be assigned to a particular data set, describing the relationships between the content of individual measures. The master classification organizes all measures into a unified content classification tree.
The coding convention in the Data Warehouse follows mnemonic approach (using English-language mnemonics), to make the data sets easier human-readable and browsable.
The URL interface is defined as follows:
Without any optional components, use the following URL structure:
This will return a list of the available instances for the specified controller.
If you specify a code of the instance, you will get detailed information about the specified instance. Specifying query parameters allows you to specify language of the response, filter data (either in instance list or data in the instance itself) or to select which parts of the instance to return.
- HOST: This is the domain of the web service. To access the API use http://dw.euro.who.int
- PORT: This is the port number for the web service. You can leave this out, or set it to the default HTTP port 80
- CONTROLLER: This is a code of the controller to retrieve data. Available controllers are:
Each controller returns different types of data.
- CODE: This is the code of the instance that you want to get.
- QUERY_PARAMETERS: There are optional query parameters, which may only be applicable for some queries. Possible parameters are:
lang— language of the response. Can be set to either EN for English or to RU for Russian. The default language is English.
filter— can be used for filtering either measures or facts within a certain measure. Filter value is a semicolon separated list of tokens in form
- a comma separated list of codes,
*" - any specified value,
$blank" - unspecified value,
- ranges like
ATTRIBUTEis integer valued),
~[year]" or "
[year]~" - nearest available year filter, where "
~" character specifies in which direction data should be searched, e.g.:
~2001- if data for the
2001year is missing, then data from the nearest previous year is returned.
Codes within the same
ATTRIBUTEare logically ORed. Different
ATTRIBUTESare logically ANDed.
CODES_LISTvalues meaning countries in specified country groups.
output— can be used in measures and categories controllers to select which part or parts of the object should be returned. Possible values are:
data, metadata, attributes, notes, classificationsfor measures and
measures, subtreefor categories. Outputparameter can be set to either of these values or to a comma separated list of them.
updated_since— is useful for retrieving information about measures and data sources that were changed since a certain date.
dataState— allows you to download codes and labels for measures and classifications that are currently unpublished in Data Warehouse.
format— defines format of the files that are exported by the API. Used only for data export and can be set to either
Requesting the list of countries in the WHO European Region by using this URL /api/v3/country_groups/WHO_EURO, the response is:
"short_name":"WHO European Region",
"full_name":"WHO European Region",
The first three properties are the codes used to identify the WHO European Region, and then the short_name, and the full_name. The short_name and the full_name may differ, so the short name can be used when showing lists, while the full name, is the complete name of the item, in the case the name of country group. These properties are always returned for the request /api/v3/country_groups/WHO_EURO, however, properties in the response depend on what request you are making.
Next is the countries item, which contains a list of the countries. Each country has several properties, in this case they are code, iso2, iso3, who_code, short_name and full_name. These properties are always returned when making the /api/v3/country_groups/WHO_EURO request.
See examples below on how to make requests to the Data Warehouse.
- Example 1 — Getting API version
- Example 2 — Retrieving a list of instances
- Example 3 — Retrieving detailed information about an instance
- Example 4 — Selecting the language of the response
- Example 5 — Selecting a measure's object parts
- Example 6 — Filtering data
- Example 7 — Filtering by country
- Example 8 — Exporting data
- Example 9 — Exporting metadata
- Example 10 — Retrieving hierarchical measure structure
- Example 11 — Data sets
Example 1 — Getting API version
To get current version of the API, use the following URL: /api/v3/version.
A new major version is released when major changes have been implemented in the response format or the functionality of the API. Old versions of API are sunset over a period of time. We recommend that your compare the current version of the API, and use the latest version whenever possible.
Example 2 — Retrieving a list of instances
You can retrieve list from individual controllers. This is useful when you need to know what items are available, for example to get a list of data sets in the Data Warehouse, or to get a list countries, their names and how they are encoded. The default language is English and you can get the Russian information if needed.
To get a list of instances use one of the following URLs:
- /api/v3/countries to get a list of countries.
- /api/v3/country_groups to get a list of country groups.
- /api/v3/data_sets to get a list of data sets.
- /api/v3/measures to get a list of measures.
Example 3 — Retrieving detailed information about an instance
To get detailed information about an instance, specify the code of the instance. The information is available in different ways. This gives you direct information by using the API, and not having to develop functionality for navigating internally in your application. The information returned from the API is always consistent.
- /api/v3/countries/UKR returns information about Ukraine.
- /api/v3/country_groups/EU_MEMBERS returns information about
EU_MEMBERScountry group which is the European Union.
- /api/v3/measures/H2020_1 returns information about
Specifying instance code in the API URL makes the API return detailed information about this instance. For example, detailed information about country contains a list of country_groups that it belongs to; detailed information about measure contains list of metadata, attributes, facts, notes and classifications related to this measure.
Example 4 — Selecting the language of the response
Use the lang parameter to select the language of the response. It can be set to EN (English) or RU (Russian). This allows you to develop bilingual applications in English and Russian. The default language is English, and if lang parameter is not specified, the response will be in English.
- /api/v3/countries?lang=EN returns information in English.
- /api/v3/country_groups/CIS?lang=RU returns information in Russian.
- /api/v3/measures/H2020_1?lang=ru is also correct; the language parameter is not case sensitive.
Example 5 — Selecting a measure's object parts
To select which parts of measure object the API should return, set output parameter to either
attributes, metadata, data, notes, classifications, data_sets or
dimensions or to a comma separated list. This way, you can select only the information you need, for example selecting data when you create a table or visualization of the data in a measure.
- /api/v3/measures/H2020_1?output=data returns only data of the measure.
- /api/v3/measures/H2020_1?output=metadata returns only metadata of the measure.
- /api/v3/measures/H2020_1?output=data,attributes returns attributes and data of the measure omitting its metadata.
Example 6 — Filtering data
The only two instances that can be filtered are measures and facts of measures. This is used in several situations. By filtering by
DATA_SOURCE returns a list of measures in that data source. You can also filter by year, or a range of years, to only receive data for the years that are relevant for your purpose.
Measures are filtered by their metadata attributes:
- /api/v3/measures?filter=DATA_SOURCE:HFA returns measures that have HFA DATA_SOURCE
- /api/v3/measures?filter=UNIT_TYPE:NUM_BEDS,NUM_DAYS returns measures that have UNIT_TYPE either NUM_BEDS or NUM_DAYS.
- /api/v3/measures?filter=DATA_SOURCE:HFA,ENHIS;UNIT_TYPE:KM2 returns measures that have DATA_SOURCE either H2020 or ENHIS and UNIT_TYPE KM2.
Facts are filtered by attributes:
- /api/v3/measures/HFA_1?filter=SEX:FEMALE,MALE returns HFA_1 facts that have SEX attribute set to FEMALE or MALE.
- /api/v3/measures/H2020_1?filter=YEAR:2004-2007,2011 returns H2020_1 facts that have YEAR attribute set to 2004, 2005, 2006, 2007 or 2011.
- /api/v3/measures/H2020_1?filter=YEAR:~2050 returns H2020_1 facts for 2050 or if the value is missing then facts from the closest year before 2050.
- /api/v3/measures/H2020_1?filter=YEAR:2000~ returns H2020_1 facts for the 2000 year or if they are missing then facts from the closest year with data after the 2000 year.
- /api/v3/measures/H2020_1?filter=COUNTRY:ALB;YEAR:2002,2003;MEASURE_TYPE:AGE_STD_RATE returns H2020_1 facts that have COUNTRY set to ALB, YEAR set to either 2002 or 2003 and MEASURE_TYPE set to AGE_STD_RATE.
- /api/v3/measures/HFAMDB_1?filter=SUBNATIONAL_MDB:* returns HFAMDB_1 facts that have SUBNATIONAL_MDB attribute specified.
- /api/v3/measures/HFAMDB_1?filter=SUBNATIONAL_MDB:$blank;SEX:ALL returns HFAMDB_1 facts that have SUBNATIONAL_MDB attributed unspecified and SEX set to ALL.
You can also filter measures and data sets by the last updated date:
- /api/v3/data_sets?updated_since=2015-12-27 returns list of data set codes that were updated after 27 Dec 2015
- /api/v3/measures?updated_since=2015-12-01 returns list of measure codes that were updated after 01 Dec 2015
- /api/v3/measures?updated_since=2015-12-18T19:00 returns list of measure codes that were updated after 18 Dec 2015 19:00
Request for certain data set or measure with updated_since parameter returns true if the data set or measure was updated since certain date and false otherwise:
- /api/v3/data_sets/HBSC?updated_since=2016-01-05 returns true because HBSC data set was updated after 05 Jan 2016
- /api/v3/data_sets/H2020?updated_since=2027-07-19T09:30 returns false because H2020 data set was not updated after 19 Jul 2027 09:30
- /api/v3/measures/H2020_10?updated_since=2027-01-01 returns false because H2020_10 measure was not updated after 1 Jan 2027
Example 7 — Filtering by country
You can filter a measure's facts by country. This is used when you want to refine the scope and only work with specific countries. You have two options to work with country groups, either setting the
COUNTRY filer to $blank, or to set
COUNTRY_GRP to *. The examples below show how the requests are made:
- /api/v3/measures/H2020_1?filter=COUNTRY:BGR,AUT,UKR returns H2020_1 facts that have COUNTRY attribute set to BGR, AUT or UKR.
- /api/v3/measures/H2020_1?filter=COUNTRY:* returns H2020_1 facts where COUNTRY attribute is specified.
- /api/v3/measures/H2020_1?filter=COUNTRY:$blank;YEAR:2003 returns H2020_1 facts where COUNTRY attribute is unspecified and YEAR set to 2003.
Example 8 — Exporting data
You can export measure data in csv or Excel format. Export the data when you need to work in an application that is not connected to the API, for example in Excel or other applications. Excel is the default format when exporting measures.
Each export request (for a measure or data set) returns a JSON response.
- /api/v3/export/H2020_1 returns H2020_1 measure data.
The first property is the status code of the export process. Possible status codes are:
- “InQueue” - file is waiting in queue to be processed,
- “Processing” - file generation has started,
- “Generated” - file processing completed and available for download,
- “Failed” - file processing failed.
Second property "time_elapsed_seconds" is the number of seconds since the file has been requested. It is only present if status property is “InQueue” or “Processing”. The property "check_status_url" provides URL to check the export process during a status of “InQueue” or “Processing”.
When the file processing is completed and available for download, the following response is displayed:
The property "generated_time" is the date and time in ISO format, and shows when the file was processed. The property "file_size_kb" shows the size of the processed file in kilobytes. The property "download_url" displays the URL for a direct download of the processed file.
Here are examples of export URLs with various filters:
Exporting one measure:
- /api/v3/export/H2020_1 exports excel file with H2020_1 measure data.
- /api/v3/export/H2020_1?format=xlsx exports Excel file with H2020_1 measure data.
- /api/v3/export/H2020_1?format=csv&lang=ru exports csv file with H2020_1 measure data in Russian.
You can also export multiple measures in one file:
- /api/v3/export?code=H2020_1,H2020_2 exports data for H2020_1 and H2020_2 measures in one Excel file.
- /api/v3/export?code=HFA_1,ENHIS_12,ENHIS_32&format=csv&lang=ru exports a zip file that contains three csv files for HFA_1, ENHIS_13 and ENHIS_32 measures in Russian.
It is also possible to export a data set entirely or some of the measures of the data set. When you want to have all measure to work offline, you can export an entire data set:
- /api/v3/export_data_set/H2020 exports zip file containing metadata and data of measures that belong to H2020 data set.
- /api/v3/export_data_set/H2020?measures=H2020_1,H2020_2,H2020_3 exports zip file containing metadata and data of H2020_1, H2020_2 and H2020_3 measures of H2020 data set.
When you need a specific part of a measure or a data set, you can filter exported measure facts by attribute. Measures in HFAMDB have facts at national and subnational level, and you can filter to export the parts you need. When you do not require facts for all measures in a data set, you filter to export only for the measures you are interested in:
- /api/v3/export/HFAMDB_1?filter=SUBNATIONAL_MDB:$blank exports excel file with HFAMDB_1 measure facts where SUBNATIONAL_MDB attribute is unspecified.
- /api/v3/export/HFAMDB_1?filter=SUBNATIONAL_MDB:*&format=csv&lang=ru exports Russian csv file with HFAMDB_1 measure facts where SUBNATIONAL_MDB attribute is specified.
- /api/v3/export_data_set/H2020?filter=COUNTRY_GRP:NORDIC exports zip file containing metadata and data of measures that belong to H2020 data set. Only measures facts that have COUNTRY_GRP equal NORDIC will be included in the export file.
- /api/v3/export_data_set/H2020?measures=H2020_1,H2020_2,H2020_3&filter=COUNTRY:UKR exports zip file containing metadata and data of H2020_1, H2020_2 and H2020_3 measures of H2020data set. Only measure facts that have COUNTRY attribute set to UKR will be included in the export file.
Example 9 — Exporting metadata
You can export metadata, when you need to have parts of metadata or the metadata from the Data Warehouse. This is done in situations when you work with metadata and data while being offline and not having continuous access to the Data Warehouse API. The export file is always in Excel format:
- /api/v3/export_metadata exports file with all metadata.
- /api/v3/export_metadata?dataState=unpublished exports file with unpublished measures and classifications.
- /api/v3/export_metadata?dataState=all exports file with all measures and classifications from the Data Warehouse.
- /api/v3/export_metadata/measure exports file with the metadata for measures.
- /api/v3/export_metadata/classification exports file with metadata for classifications.
Example 10 — Retrieving hierarchical measure structure
Use the classifications request to get available measure classifications. classifications are a way to organize measures in the Data Warehouse, so they can be browsed in a hierarchy.
- /api/v3/classifications returns list of measure classifications.
Use the categories controller to get detailed information about classifications like sub-categories or measures assigned to subcategories:
- /api/v3/categories/D returns the entire classification tree with categories, sub-categories, sub-sub-categories (if they exist) and measures related to them for classification D.
- /api/v3/categories/D03_00 returns measures assigned to category D03_00 and its sub-categories (if exist).
- /api/v3/categories/D03_00?output=measures returns measures assigned to category D03_00 without it's sub-categories.
- /api/v3/categories/D03_00?output=subtree returns sub-categories of category D03_00 without measures assigned to it.
- /api/v3/categories returns entire classification tree for all classifications with measures assigned to each category.
- /api/v3/categories?output=subtree returns classification tree for all classifications without measures.
- /api/v3/measures/HFA_1?output=classifications each measure has classifications property that contains list of categories that the measure is assigned to grouped by classifications. This can be used for getting a list of categories that the measure is assigned to and then getting related measures.
Example 11 — Data sets
You can get a list of data sets in the Data Warehouse, or get a list of measures in a data set. Use this when you want to build lists of what is available from the Data Warehouse.
- /api/v3/data_sets returns list of all available data sets.
- /api/v3/data_sets/H2020 returns list of all measures of the data set.
To get measure data in context of certain data set:
- /api/v3/data_sets/H2020/H2020_1 returns H2020_1 measure data in context of H2020 data set with data set specific country list, data set notes etc.