The Global Health Observatory
Explore a world of health data
The Athena web service provides a simple query interface to the World Health Organization's data and statistics content. This document describes version 1.0 of the API.
Table of contents
URL Specification
The URL interface is defined as follows:
http://HOST[:PORT]/PATH/athena/INSTANCE/[DIMENSION[/CODE[,CODE2[,CODEn]][.EXTENSION][?QUERY_PARAMETERS]]]Without any of the optional components, the URL structure
http://HOST:PORT/PATH/athena/INSTANCE/returns a list of the available dimensions to target for download (Example 1). If you specify a dimension but nothing else, you will get the list of codes available for that dimension (Example 2). If you specify both the dimension and the code you will retrieve the corresponding data (Example 3). Multiple targets can be specified by separating them with a comma character ( Example 8).
| HOST | ||
| This is the name of the machine providing the web service. In order access public WHO data, use apps.who.int | ||
| PORT | ||
| This is the port number for the web service. In order to access public WHO data, you can leave this out, or set it to the default HTTP port, 80. | ||
| PATH | ||
| The application path for the web service. All WHO public data available from this web service are in the gho path. | ||
| INSTANCE | ||
| This is the specific database that you wish to access. The WHO public data is available in the api instance. | ||
| DIMENSION | ||
| The dimension you wish to target. See example 2 for the list of dimensions that are available. | ||
| CODE, CODE2, ... CODEn | ||
| The specific code(s) for which you wish to download data. Example 3 and example 8 demonstrate how to download life expectancy statistics from the Global Health Observatory. | ||
| QUERY_PARAMETERS | ||
| apikey | The API key token that has been given to you to enable access to the Athena web service. This token is currently optional, but if you have one, you should use it in all queries so that your services and applications are not interrupted when the apikey system is officially activated. | |
| format | The output format you wish to use. The default is XML defined by the ghodata.xsd file | |
| profile | A modifier that allows you to specify different versions of the requested format, for example an application specific JSON output | |
| filter | Restricts the data returned by specifying filtering codes The filter value is a semicolon separated list of tokens of the formDIMENSION:CODE. Specific codes belonging to the same dimension are logically ORed. The different groups
of dimensions are logically ANDed. For example:
COUNTRY:CAN;YEAR:2005;YEAR:2010will only return data for Canada for the years 2005 and 2010. There are two special filter charaters. * is used to denote that the specified dimension must be present and set with any value and - denotes that the specified dimension MUST NOT be set, ie must be null. | |
| asof | An optional parameter allowing the user to specify a datetime stamp that will show the result as it would have looked on that particular date. This is useful when a collection of data has been retroactively changed, as often happens when
we update statistics based on improved methods and models, as well as receive updated reporting data. This function is currently blocked in the public system. | |
| target | Overides the target specifed in the DIMENSION and CODE components of the URL. This is used to create URLs where the path name needs to have specific structure for the system or application making the query. The values for this parameter consist of the DIMENSION code, followed by a slash, then a list of 1 or mode CODE, separated by commas. | |
| language | Specify a language code. The web service will do it's best to accomodate, based on available translation strings. If it does not have strings in the specified language, it will return the English string. | |
| callback jsonp | When specifying a JSON format, adding the callback or jsonp parameter will wrap the returned javascript in the specified function. | |
| cache | The cache parameter is used to force certain caching behaviours when the cache is enabled on the web service. The only currently allowed option is refresh which forces the web service to regenerate the underlying XML even if there is a non-expired version of the data currently available in the cache. | |
| x-* | x- parameters are arbitrary. They are passed to the web services and returned through the QueryParameter element in the XML response. They are a way of providing user specified input to XSLT transforms. Note that when X parameters are used, the transformed response (generated if you have specified format and profile parameters) will not be cached however the underlying XML will continue to be cached. | |
XML schema
The XML returned is a structural format intended for transformation into something that can be displayed, downloaded, or exchanged. It is not intended as an exchange format itself.
Available formats
The service currently understands the following combinations of format and profile parameter values:
| profile=excel | Provides a SpreadsheetML version of the data that can be loaded into Excel. |
| format=csv | Provides a coded version of the requested data or metadata in CSV format. |
| format=csv&profile=text | Provides a version of the requested data or metadata in CSV format with all coded values resolved to the display strings in the selected language, or English if the strings are not available. |
| format=csv&profile=verbose | Provides a combined version of the requested data or metadata in CSV format with all coded values, and the corresponding display strings in the selected language, or English if the strings are not available. |
| format=json | Outputs the requested data or metadata in json. If you have specified a function name using the callback or jsonp parameter, the output will be encapsulated accordingly. |
| format=json&profile=simple | Outputs the requested data in a simplified json format where all codes have been resolved to the corresponing display strings. If you have specified a function name using the callback or jsonp parameter, the output will be encapsulated accordingly. Note that this option does not give a very useful result when you are requesting only metadata. |
Examples
A set of examples illustrating the use of the API is available here.
Additional information
If you would like to have more information regarding the API, please send an email to [email protected]