Back to gateway.euro.who.int
DW Home API Specifications Swagger Release notes Data Management Tool

Specifications

Web service provides a simple query interface to the World Health Organization's data and statistics content. This document describes version 5.0.0.75 of the API.

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 interact with data stored in DW. 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.

Indicator

observed value of a variable, quantifiable characteristics which describes the health of a population.

Measure

set of facts with unique code and bilingual name that are defining an indicator.

Metadata

defines WHO Europe DW data structure including Measures, Attributes, Measure-Attribute Codes, Fact-Attribute Codes and Notes.

Fact

the set of attribute codes that belongs to measured value and value itself.

Attribute

there are fact and measure related attributes. Fact attribute can be related to one of 3 main dimensions: Place, Time or Person. Measure attribute describes entire measure (EXTERNID, DATA_SOURCE) or is common for all facts (UNIT_TYPE).

Code

unique short name that is used for identifying entity in the DW. Usually upper case with Latin letters, numbers and underscore.

Data source

is measure attribute that defines the area (division?) that data comes from.

Data set

set of measures that are used for whatever purpose: visualization, data mining, investigations, ...

Note

is plain text or HTML data related to Measures or Data sources that are collected in the DW.

The URL interface is defined as follows:
http://HOST[:PORT]/api/v5/CONTROLLER[/CODE][?QUERY_PARAMETERS]
Without any of the optional components, the following URL structure:
http://HOST/api/v5/CONTROLLER

Returns a list of the available instances for the specified controller.

If you specify a code of the instance you will get detailed information about 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 https://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 from. Available controllers are:

  • countries
  • country_groups
  • data_sets
  • measures
  • version
  • export
  • export_metadata
  • export_data_set
  • classifications
  • categories

Each controller returns different kind of data.

CODE

This is the code of the instance that you want to get

QUERY_PARAMETERS

This is additional query parameters. Possible parameters are:

  • lang — language of the response. Can be set either to EN for English or to RU for Russian. Default language in 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. output parameter can be set to either of these values or to a comma separated list of them.

  • updated_since — useful for retrieving information about measures and data sources that were changed since 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 API provides data in JSON format. For each specific CONTROLLER structure of the returned object is different. See examples for more clarification.


Example 1 — Getting API version

To get current version of the API use the following URL: /api/v5/version.


Example 2 — Retrieving a list of instances

To get a list of instances use one of the following URLs:


Example 3 — Retrieving detailed information about an instance

To get detailed information about an instance you should specify code of the instance to get:

Specifying instance code in the API URL makes 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

To select the language of the response lang parameter is used. It can be set to either EN or RU for English or Russian respectively:

Default language is English so if lang parameter is not specified English response is returned.


Example 5 — Selecting measure's object parts

To select which part 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 of them:


Example 6 — Filtering data

The only two instances that can be filtered are measures and measure's facts. Measures are filtered by their metadata attributes:

Facts are filtered by attributes:

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

Request for certain data set or measure with updated_since parameter returns true if this data set or measure was updated since certain date and false otherwise:


Example 7 — Filtering by country

You can filter measure's facts by country:

There are some exceptions in the logic of filtering when applied to attributes COUNTRY and COUNTRY_GRP. Some examples:


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/v5/export/H2020_1 returns H2020_1 measure data.

{
   "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:

You can also export multiple measures in one file:

It is also possible to export data set entirely or only some of the measures of the dataset:

You can also filter exported measures facts by some attribute:


Example 9 — Exporting metadata

You can export metadata in excel format:


Example 10 — Retrieving hierarchical measure structure

To get available measure classifications you can use classifications request:

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


Example 11 — Data sets

To get list of data sets or list of data set measures:

To get measure data in context of certain data set: