Find out about the API

Data Sources

Mortality Data drawn from the WHO ICD-10 (parts 1 and 2) raw data file(accessed November 2019).
ICD-10 codes taken from the Centers for Medicare & Medicaid Services website and the WHO Mortality Database Documentation(accessed November 2019).

Datasets Available

This API returns data in JSON format with all values as strings.

The following data-sets are available:

  • WHO Country codes
  • WHO 'Sex' codes and their descriptions
  • WHO 'Admin' codes and their descriptions
  • WHO 'Subdiv' codes and their descriptions
  • WHO Age format codes and their descriptions
  • WHO Infant age format codes and their descriptions
  • Country populations (from 1950)
  • ICD codes and descriptions (currently only ICD-10)
  • Mortality (cause of death) statistics (from 1998 for certain countries)
  • Mortality (cause of death) statistics adjusted for population

Notes

General

All get variables should be written as the associated WHO code.
e.g. Male = 1, UK = 4308, All Causes = AAA
To find the codes please use the codes page

Population Data

Population and live births are both in units. Population figures are mid-year populations as stated by member countries.

ICD Codes

Y34 and Y349 refer to the sum of all deaths from accidental deaths V00-Y89 for countries reporting with list 103 and 104 respectively.

If a country reports with a 4 character code in the 10M list, the death will not be counted in the 3 character code total (all numbers are mutually exclusive).

Mortality Data

Some cause of death ICD codes listed in the mortality database do not appear in any official ICD documentation, specifically related to the W## and Y## codes - I have contacted the WHO for clarification on this issue.

The mortality search algorithms also try to find matching descriptions in other code lists if the one specified by the user doesn't exist for specified countries (including adding / removing "unspecified" from the description). This allows users to compare matching or similar data (if an exact match doesn't exist).

Population Adjusted Mortality Data

In some cases there is population data but no mortality data, or vice versa. In these situations the data points are removed so as to avoid confusion due to mixing data formats.


Quick Start Guide

To use the API from custom scripts it is likely the endpoint you wish to use requires an API key; To obtain your API key first sign up. You will then be taken to your profile page - click the API key button.

Copy the whole key (being careful not to copy any trailing whitespace) and pass this as a header with key = "api_key" in your API call.

Below are some example paths and the data they will return

Search for Countries

e.g. Search for all counties containing string "ka"
GET /api/country-search/ka

ICD Search

e.g. Search for all ICD codes that contain the string "boil"
GET /api/icd-search/boil

Find Multiple Mortality Entries

e.g. Return the total deaths for all causes for males in the UK and Algeria in years 2000 and 2002
GET /api/mortality-search-multiple?country=4308,1020&year=2000,2002&sex=1&admin=&subdiv=&cause=AAA

Find Multiple Population Adjusted Mortality Entries

e.g. Return population adjusted mortality data for males and females in the United Kingdom in 2006 caused by "Airgun discharge (undetermined intent)":
GET /api/mortality-adj-search?country=4308&year=2006&cause=Y240


Path list: