European Health
Information Gateway

Tutorials and first steps
Gateway Country profiles Data
Data
Indicators Explorer
Tutorials and first steps Visit the main WHO website?
Databases
European Health for All database (HFA-DB) Health information system and data governance Artificial Intelligence for Health in the WHO European Region Assistive Technology European Programme of Work Digital Health European mortality database (MDB) Rehabilitation Health-enhancing physical activity European database on human and technical resources for health (HlthRes-DB) Environment and Health Information System (ENHIS) Financial protection in the European Region
Monitoring
Child and adolescent health Seasonal influenza vaccination policies and coverage
Reporting
Health Behaviour in School-aged Children (HBSC) Maternal nutrition, physical activity and weight gain during pregnancy Antimicrobial resistance Global nutrition policy survey Status of child and adolescent health policies in Europe
Archive
Health 2020 indicators Global eHealth survey 2015 Joint Monitoring Framework (JMF)
Data Databases Monitoring Reporting Archive
Tutorials and first steps Visit the main WHO website?
API

API Specifications

Table of contents:

API Specifications

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:

 

Glossary/Definitions

  • 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.
  • JSON - JavaScript Object Notation (JSON) is an open standard format that uses human-readable text to represent data objects consisting of attribute-value pairs.
  • 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/v5/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:

http://HOST[:PORT]/api/v5/CONTROLLER[/CODE][?QUERY_PARAMETERS]

Without any optional components, use the following URL structure:

http://HOST/api/v5/CONTROLLER

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:
    • countries
    • country_groups
    • data_sets
    • measures
    • version
    • export_metadata
    • export_data_set
    • classifications
    • categories

      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 ATTRIBUTE:CODES_LIST.
      CODES_LIST is:
      • a comma separated list of codes,
      • " * " - any specified value,
      • " $blank " - unspecified value,
      • ranges like 1999-2004 (if ATTRIBUTE is 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 2001 year is missing, then data from the nearest previous year is returned.

      Codes within the same ATTRIBUTE are logically ORed. Different ATTRIBUTES are logically ANDed.

      COUNTRY attribute supports COUNTRY_GRP codes as CODES_LIST values 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, classifications for measures and measures, subtree for 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 xlsx or csv.

 

The responses from the Data Warehouse API are in JavaScript Object Notation (JSON). JSON is a format for data exchange that can be read and understood by machines and humans. The structure of the returned object is different for each CONTROLLER.

Requesting the list of countries in the WHO European Region by using this URL /api/v5/country_groups/WHO_EURO, the response is:

{  
    "code":"WHO_EURO",
    "short_name":"WHO European Region",
    "full_name":"WHO European Region",
    "countries":[  
       {  
          "code":"ALB",
          "iso2":"AL",
          "iso3":"ALB",
          "who_code":"ALB",
          "short_name":"Albania",
          "full_name":"Albania"
       },
       {  
          "code":"AND",
          "iso2":"AD",
          "iso3":"AND",
          "who_code":"AND",
          "short_name":"Andorra",
          "full_name":"Andorra"
       },
       (...)
   ]
 }

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/v5/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/v5/country_groups/WHO_EURO request.

See examples below on how to make requests to the Data Warehouse.

 

To get current version of the API, use the following URL: /api/v5/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.

 

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:

 

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.

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.

 

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.

 

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.

 

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:

Facts are filtered by attributes:

You can also filter measures and data sets by the last updated date:

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:

 

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:

 

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.

{
    "status": "InQueue",
    "time_elapsed_seconds": 0,
    "check_status_url":"/api/v5/export/status/c2df1c001eb64309b12f97a920bc3ecc"
}

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:

{
    "status": "Generated",
    "generated_time": "2018-01-21T13:45:21.2249016",
    "file_size_kb": 59,
    "download_url":"/api/v5/export/download/6522933299f54d20b58dd013b506dd2"
}

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:

You can also export multiple measures in one file:

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:

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:

 

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:

 

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.

Use the categories controller to get detailed information about classifications like sub-categories or measures assigned to subcategories:

 

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.

To get measure data in context of certain data set: