An API to allow easier querying of the World Health Organization's Mortality Data.
Check the official documentation at our website
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).
This API returns data in JSON format with all values as strings.
The following datasets are available:
- WHO Country codes
- WHO Sex codes and their meanings
- WHO 'Admin' codes and their meanings
- WHO 'Subdiv' codes and their meanings
- WHO Age format codes and their meanings
- WHO Infant age format codes and their meanings
- Country populations (from 1950)
- ICD codes and description (currently only ICD-10)
- Mortality (cause of death) statistics (from 1998 for certain countries)
- Mortality (cause of death) statistics adjusted for population
The following endpoints are available (grouped by section):
Return all country names and associated codes used in WHO Mortality database.
GET /api/country-list
Return the name and code of a country (case insensitive).
GET /api/country/<country_name>
e.g.
GET /api/country/djibouti
{
"id": 14,
"code": "1120",
"name": "Djibouti"
}
Return all countries with names that contain a search term
GET /api/country-search/<search_term>
e.g.
GET /api/country-search/ka'
{
"id": 145,
"code": "3365",
"name": "Sri Lanka"
},
{
"id": 178,
"code": "4182",
"name": "Kazakhstan"
}
Endpoints related to the 'Sex' section of the Mortality Database (Short version: 1 = Male, 2 = Female, 9 = Unspecified)
Return all sex codes used in the Mortality Database
GET /api/sex-list
Return the code for a know sex
GET /api/sex-desc/<sex_name>
e.g.
GET /api/sex-desc/female
{
"name": "female",
"code": "2"
}
Endpoints related to the 'Admin' section of the Mortality Database
Return all admin codes and descriptions used in WHO Mortality database.
GET /api/admin-list
Return the description of a specific admin code for a specific country.
GET /api/admin/<admin_code>/<country_code>
e.g.
GET /api/admin/901/3150
{
"admin": "901",
"country": {
"code": "3150",
"name": "Israel"
},
"description": "Jewish Population"
}
Endpoints related to the 'Subdiv' section of the Mortality Database
Return all subdiv codes and descriptions used in WHO Mortality database.
GET /api/subdiv-list
Return the description of a specific subdiv code.
GET /api/subdiv/<subdiv_code>
e.g.
GET /api/subdiv/A35
{
"code": "A35",
"description": "Selected Urban and Rural Areas"
}
Endpoints related to the 'Age format' section of the Mortality Database
Return all age format codes and their year cut-off boundaries used in WHO Mortality database.
GET /api/age-format-list
Return the description of a specific age format code.
GET /api/age-format-code/<age_format_code>
e.g.
GET /api/age-format-code/08
{
"age_format_code": "08",
"pop2": "0",
"pop3": "1-4",
"pop4": "empty4",
"pop5": "empty5",
"pop6": "empty6",
"pop7": "5-14",
"pop8": "empty8",
"pop9": "15-24",
"pop10": "empty10",
"pop11": "25-34",
"pop12": "empty12",
"pop13": "35-44",
"pop14": "empty14",
"pop15": "45-54",
"pop16": "empty16",
"pop17": "55-64",
"pop18": "empty18",
"pop19": "65+",
"pop20": "empty20",
"pop21": "empty21",
"pop22": "empty22",
"pop23": "empty23",
"pop24": "empty24",
"pop25": "empty25",
"pop26": "Unknown"
}
Endpoints related to the 'Infant Mortality' section of the Mortality Database
Return all infant age format codes and their day cut-off boundaries used in WHO Mortality database.
GET /api/infant-age-format-list
Return the description of a specific infant mortality age format code.
GET /api/-infant-age-format-code/<infant_age_format_code>
e.g.
GET /api/infant-age-format-code/01
{
"infant_age_format_code": "01",
"infant_age1": "0 days",
"infant_age2": "1-6 days",
"infant_age3": "7-27 days",
"infant_age4": "28-365 days"
}
Note: Population and live births are both in units. Population figures are mid-year populations as stated by member countries.
All terms used in the population API queries should be in terms of WHO codes which can be found using other endpoints in this API
Return a dictionary of all available population data
GET /api/population-list
Get raw population data for given country, year, sex, admin or subdiv (or any combination thereof). Response returned as a list and multiple entries are allowed.
GET /api/population-search?country=<country>&year=<year>&sex=<sex>&admin=<admin>&subdiv=<subdiv>
Variables (variable name) = format: country = country code, year, sex = sex code, admin = admin code, subdiv = subdiv code
e.g.
Return population data for males and females in the United Kingdom in 1989:
GET /api/population-search?country=4308&year=1989
Get raw population data for given country, year, sex, admin or subdiv (or any combination thereof).
Returns data if only one population entry matches the query
GET /api/population-one?country=<country>&year=<year>&sex=<sex>&admin=<admin>&subdiv=<subdiv>
e.g.
Return population data for only males in the United Kingdom in 1989:
GET /api/population-one?country=4308&year=1989&sex=1
Endpoints related to the ICD codes including search for descriptions and codes across multiple list versions used by WHO in mortality data.
Find descriptions of all different code lists used in Mortality Data.
GET /api/icd-code-list-list
Find the description of a specific code list.
GET /api/icd-code-list/<code>
e.g.
GET /api/icd-code-list/103
{
"list": "103",
"description": "3 Character ICD10 codes"
}
Find the description of a certain code in a certain list. (If list is unknown use the ICD Search endpoint.)
NOTE 1: Y34 and Y349 respectively refer to the sum of all deaths from accidental deaths V00-Y89 for countries reporting with list 103 and 104 respectively
NOTE 2: 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).
GET /api/icd/<list>/<code>
e.g.
GET /api/icd/104/Y25
{
"list": "104",
"code": "Y25",
"description": "Contact with explosive material (undetermined intent)"
}
Search the ICD with a search term (searches both codes and description)
GET /api/icd-search/<search_term>
e.g.
GET /api/icd-search/boil
{
"results": [
{
"list": "103",
"code": "W35",
"description": "Explosion and rupture of boiler"
},
{
"list": "104",
"code": "W35",
"description": "Explosion and rupture of boiler"
},
{
"list": "10M",
"code": "W35",
"description": "Explosion and rupture of boiler"
}
]
}
Return all ICD codes and their descriptions in all lists used in Mortality Database
GET /api/icd-list
Endpoints related to the WHO Mortality Database. Each mortality database entry details the number of deaths in a given country in any given year for any given sex from a certain cause. Mortality data starts in 2005.
NOTE: 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.. cause of death codes. I have contacted the WHO for clarification on this issue.
Get raw mortality data for given country, year, sex, admin or subdiv and cause (or any combination thereof). Response returned as a list and multiple entries are allowed.
GET /api/mortality-data-search?country=<country>&year=<year>&sex=<sex>&admin=<admin>&subdiv=<subdiv>&cause=<cause>
Variables (variable = format): country = country code, year, sex = sex code, admin = admin code, subdiv = subdiv code, cause = cause code. All codes can be found from the respective endpoints
e.g.
Return mortality data for males and females in the United Kingdom in 2006 caused by "Airgun discharge (undetermined intent)":
GET /api/mortality-data-search?country=4308&year=2006&cause=Y240
Get raw mortality data for given country, year, sex, admin or subdiv and cause (or any combination thereof).
Returns data only if only one mortality entry matches the query
GET /api/mortality-data-one?country=<country>&year=<year>&sex=<sex>&admin=<admin>&subdiv=<subdiv>&cause=<cause>
e.g.
Return mortality data for only males in the United Kingdom in 2016 caused by "Driver of special agricultural vehicle injured in traffic accident":
GET /api/mortality-data-one?country=4308&year=2016&sex=1&cause=V840
Get raw mortality data for lists of given country, year, sex, admin or subdiv and cause (or any combination thereof). Response returned as a list and multiple entries are allowed.
GET /api/mortality-search-multiple?country=<country>,<country>,...&year=<year>,<year>,...&sex=<sex>,<sex>,...&admin=<admin>,<admin>,...&subdiv=<subdiv>,<subdiv>,...&cause=<cause>,<cause>,...
Return mortality data for males and females in the United Kingdom and Croatia in 2005 and 2006 caused by "Airgun discharge (undetermined intent)":
GET /api/mortality-data-search?country=4308,4038&year=2005,2006&cause=Y240&sex=1,2
Endpoints related to the WHO Mortality Database with all mortalities adjusted for population (per 100,000) - also known as ASDR per 100,000. All other factors are the same as for the mortality data detailed above.
NOTE: Some cause of death ICD-10 codes listed in the mortality database do not appear in any official ICD documentation, specifically related to the W.. and Y.. cause of death codes. I have contacted the WHO for clarification on this issue. NOTE: In some cases there is population data but no mortality data, or vice versa. In these situations the data point is removed so as to avoid confusion due to mixing of age-specific and absolute data.
Get adjusted mortality data for given country, year, sex, admin or subdiv and cause (or any combination thereof). Response returned as a list and multiple entries are allowed.
GET /api/mortality-adj-search?country=<country>&year=<year>&sex=<sex>&admin=<admin>&subdiv=<subdiv>&cause=<cause>
Variables (variable = format): country = country code, year, sex = sex code, admin = admin code, subdiv = subdiv code, cause = cause code. All codes can be found from the respective endpoints
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
Get adjusted mortality data for given country, year, sex, admin or subdiv and cause (or any combination thereof).
Returns data only if only one mortality entry matches the query
GET /api/mortality-adj-one?country=<country>&year=<year>&sex=<sex>&admin=<admin>&subdiv=<subdiv>&cause=<cause>
e.g.
Return population adjusted mortality data for only males in the United Kingdom in 2016 caused by "Driver of special agricultural vehicle injured in traffic accident":
GET /api/mortality-adj-one?country=4308&year=2016&sex=1&cause=V840
Get population adjusted mortality data for lists of given country, year, sex, admin or subdiv and cause (or any combination thereof). Response returned as a list and multiple entries are allowed.
GET /api/mortality-search-multiple?country=<country>,<country>,...&year=<year>,<year>,...&sex=<sex>,<sex>,...&admin=<admin>,<admin>,...&subdiv=<subdiv>,<subdiv>,...&cause=<cause>,<cause>,...
Return population adjusted mortality data for males and females in the United Kingdom and Croatia in 2005 and 2006 caused by "Airgun discharge (undetermined intent)":
GET /api/mortality-data-search?country=4308,4038&year=2005,2006&cause=Y240&sex=1,2
Every attempt has been made to keep data true to the original raw data files but veracity cannot be guaranteed. If this is important, download the data directly or use one of the WHO's data querying services All analyses, interpretations or conclusions drawn from this API or found on this website are credited to the authors, not the WHO (which is responsible only for the provision of the original information). For more information visit the WHO website