ICD-API (version 2)

In order to use version 2 of the API, you need to add API-Version request header with the value v2 to all calls made to the API

ICD API is an HTTP based REST API that allows programmatic access to the International Classification of Diseases (ICD).

This document provides an overview of the ICD-API version 2. More detailed API-Reference is available as an Open-API (swagger) documentation.

This document and the API-Reference is aimed for software developers who would like to consume the ICD-API in their software. For more information on ICD-11 itself, you may see the ICD-11 Reference Guide

ICD URIs and API endpoints

ICD-11 uses URIs as unique identifiers for individual classification entities in the foundation component and in the linearizations (tabular lists). One important thing to know about ICD-API is that these URIs are actually the endpoints of our API. For example, the URI for Cholera in the foundation component is (http://id.who.int/icd/entity/257068234) and this URL is the endpoint in our API that will give you information about "cholera" in ICD-11

Usage of https

All communication made to the APIs are encrypted (i.e. only https is allowed). All http requests will be automatically redirected to the https variants.

Even though there is this automated redirection, we recommend directly calling to the https endpoints as this will work faster.

E.g. When using the API, instead of requesting http://id.who.int/icd/entity/257068234 as in the URI, request https://id.who.int/icd/entity/257068234

The URIs of the ICD entities will have http not https so you need to make this change in your code to prevent the overhead of the redirect.

Scope

The ICD-API covers the following content:

We provide multiple versions of the above. Please see the Supported Classifications document for a full list of supported releases

The ICD Foundation Component

Foundation Component is a collection of ALL ICD entities like diseases, disorders... It represents the whole ICD universe. The ICD entities in the Foundation Component:

  1. are not necessarily mutually exclusive;
  2. allow multiple parenting (i.e. an entity may be in more than one branch, for example tuberculosis meningitis is both an infection and a brain disease)

For more information see Foundation and Tabular lists from ICD-11 Reference guide

The ICD11 Linearizations (Tabular lists)

A linearization is a subset of the foundation component, that is:

  1. fit for a particular purpose: reporting mortality, morbidity, primary care or other uses;
  2. composed of entities that are Mutually Exclusive of each other;
  3. each entity is given a single parent.

Linearization is similar to the classical print versions of ICD Tabular List (e.g. volume I of ICD-10 or other previous editions). The main linearization of ICD-11 is Mortality and Morbidity Statistics (MMS). Various linearizations could be built at different granularity, use case or other purposes such as for Primary Care, Clinical Care or Research. The linkage from the foundation component to a particular linearization will ensure consistent use of the ICD.

For more information see Foundation and Tabular lists from ICD-11 Reference guide

Authentication

In order to be able to use the ICD APIs, first you need to create an account on the ICD API Home page: https://icd.who.int/icdapi

The APIs use OAuth 2 client credentials for authentication. Once you register and login to this site, you could get a client id and client secret to be used for authentication. This is done by clicking on the View API access key link.

More information on authentication can be found in the ICD API Authentication document

All communication made to the access management site and the APIs are encrypted (i.e. only https is allowed) However if you refer to the http variants of the URLs, they will be automatically redirected.

Content Negotiation for the format

The services behind the URIs provide the classification in different formats: The services support json-ld and rdf/xml formats. To be able to retrieve a specific format, we need to use content negotiation by setting the Accept Header as following:

Format Accept header values
JSON-LD Accept: application/json
RDF/XML Accept: application/rdf+xml
Accept: application/xml

JSON-LD (JSON for Linked Data), is a syntax defined by W3C for encoding Linked Data using JSON. JSON-LD documents could be consumed as simple JSON files.

RDF/XML is a syntax defined by the W3C to express (serialize) an RDF graph as an XML document.

We recommend using the JSON-LD format if you don't have a specific reason to use RDF/XML. There are several reasons:

The search results are always provided in plain JSON format regardless of the Accept Header

Schemas

The content of the classification is defined by two schemas:

Content Negotiation for the Language

The services are multilingual. They support content negotiation using Accept-Language header. We are going to provide other language versions as translations of ICD-11 are completed.

ICD-API Reference

More detailed API-Reference is available as an Open-API (swagger) documentation. Here, you will find each and every endpoint and explanation of the fields returned by the API in a very detailed fashion.

This standard format of formally documenting the API has several additional benefits

The swagger documentation only supports the JSON(-LD) format.