The Foundation API from World Health Organization (WHO) — 4 operation(s) for foundation.
openapi: 3.0.1
info:
title: ICD Foundation API
description: "\n<p>\nICD-API is a REST API that allows programmatic access to the International Classification of Diseases (ICD).\n</p><p>\nFor most users that require accessing the ICD-11 statistical classification with codes, you need to use the <b>Linearization</b> endpoints with the linearizationId set to <b>mms</b>\n</p><p>\n<b>Foundation</b> endpoints provide information on the Foundation Component of ICD-11. \n</p><p>\n<b>ICD10</b> endpoints serves ICD-10 releases. Please note that functionality on the ICD-10 endpoints are limited. (i.e. the search is not provided)\n</p><p>\nFor more information on the API please see the <a href=\"https://icd.who.int/icdapi\">ICD-API home page </a>\n</p>\n"
license:
name: ' ICD-11 Terms of Use and License Agreement '
url: https://icd.who.int/en/docs/icd11-license.pdf
version: v2.6.0
security:
- oauth2:
- icdapi_access
tags:
- name: Foundation
paths:
/icd/entity:
get:
tags:
- Foundation
summary: This endpoint returns basic information on the latest release of the ICD-11 Foundation together with the top level Foundation entities.
operationId: GetFoundation
parameters:
- name: releaseId
in: query
description: "This is an optional parameter and if ignored, the API will return values from the latest released version of the Foundation.\r\n If provided, the API will respond using that particular release. The values are like 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications"
schema:
type: string
- name: API-Version
in: header
description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
required: true
schema:
type: string
- name: Accept-Language
in: header
description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/TopLevelFoundation'
application/ld+json:
schema:
$ref: '#/components/schemas/TopLevelFoundation'
'401':
description: Unauthorized
/icd/entity/{id}:
get:
tags:
- Foundation
summary: This endpoint provides you information on a specific ICD-11 foundation entity
operationId: GetFoundationEntity
parameters:
- name: id
in: path
description: Numeric part at the end of the URI for an entity
required: true
schema:
type: string
- name: releaseId
in: query
description: "This is an optional parameter and if ignored, the API will return values from the latest released version of the Foundation.\r\n If provided, the API will respond using that particular release. The values are like 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications"
schema:
type: string
- name: include
in: query
description: "Some property values such as ancestor and decendant lists are not provided in the response by default. However, it is possible\r\n to request them. These properties are <i>ancestor, descendant and diagnosticCriteria.</i> For example, if you set include=ancestor the returned response will \r\n include all ancestor entity URIs for the requested entity.\r\n A comma separated list could be used to request multiple optional property values. e.g. include=ancestor,descendant"
schema:
type: string
- name: API-Version
in: header
description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
required: true
schema:
type: string
- name: Accept-Language
in: header
description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/FoundationEntity'
application/ld+json:
schema:
$ref: '#/components/schemas/FoundationEntity'
'401':
description: Unauthorized
'404':
description: Not Found
/icd/entity/autocode:
get:
tags:
- Foundation
summary: "Provides the best matching classification entity (its code and URI) for the provided diagnostic text. see AutoCodingSearchResult\r\nschema for information on the response."
operationId: AutoCodeFoundation
parameters:
- name: searchText
in: query
description: Input text for which the matching entity to be provided
schema:
type: string
- name: releaseId
in: query
description: 'The id for the release. This is generally formatted like this: 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications'
schema:
type: string
- name: subtreesFilter
in: query
description: Optional parameter. Comma separated list of URIs. If provided, the search will be performed on the entities provided and their descendants
schema:
type: string
- name: matchThreshold
in: query
description: score is a value between 0 and 1 that indicates the similarity between the input text and the matched term. matchThreshold the minimum score to be included in the output. The API will use default value if not provided
schema:
type: number
format: double
- name: API-Version
in: header
description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
required: true
schema:
type: string
- name: Accept-Language
in: header
description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/AutoCodingSearchResult'
'401':
description: Unauthorized
/icd/entity/search:
get:
tags:
- Foundation
summary: "This endpoint is for searching the foundation component of the ICD-11. The search can be customized using the parameters as described. Search endpoint accepts both GET and POST requests. If the size of the request is too large, you may need to use POST\r\nas HTTP GET has a size limit of 2K"
operationId: SearchFoundation
parameters:
- name: q
in: query
description: Text to be searched. Having the character % at the end will be regarded as a wild card for that word
schema:
type: string
- name: subtreesFilter
in: query
description: Optional parameter. Comma separated list of URIs. If provided, the search will be performed on the entities provided and their descendants
schema:
type: string
- name: chapterFilter
in: query
description: Optional, comma or semicolon separated list of chapter codes eg:01;02;21 When provided, the search will be performed only on these chapters
schema:
type: string
- name: useFlexisearch
in: query
description: "Changes the search mode to flexible search.\r\n - In the regular search mode, the Coding Tool will only give you results that contain all of the words that you've used in your search. It accepts different variants or \r\n synonyms of the words but essentially it searches for a result that contains all components of your search. Whereas in flexible search mode, the results do not have to \r\n contain all of the words that are typed. It would still try to find the best matching phrase but there may be words in your search that are not matched at all\r\n - It is recommended to use flexible search only when regular search does not provide a result"
schema:
type: boolean
default: false
- name: flatResults
in: query
description: "Optional parameter. Default value false. If set to true the search result entities are provided in a nested data structure\r\n representing the ICD-11 hierarchy. Otherwise they are listed as flat list of matches"
schema:
type: boolean
default: true
- name: propertiesToBeSearched
in: query
description: "The properties to be searched. By default the system searches, Title, Synonyms and FullySpecifiedName.\r\n The valid values that could be used are: \"Title\", \"Synonym\", \"NarrowerTerm\", \"FullySpecifiedName\", \"Definition\" and \"Exclusion\"\r\n More than one property could be used with \",\" as the separator. In this case the results will include matches from any one of these properties"
schema:
type: string
- name: releaseId
in: query
description: "This is an optional parameter and if ignored, the API will return values from the latest released version of the Foundation.\r\n If provided, the API will respond using that particular release. The values are like 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications"
schema:
type: string
- name: highlightingEnabled
in: query
description: "Optional. Default is true, if set to false the search result highlighting is turned off\r\n and the results don't contain special tags for highlighting where the results are found within the text"
schema:
type: boolean
default: true
- name: API-Version
in: header
description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
required: true
schema:
type: string
- name: Accept-Language
in: header
description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ISearchResult'
'401':
description: Unauthorized
post:
tags:
- Foundation
summary: "This endpoint is for searching the foundation component of the ICD-11. The search can be customized using the parameters as described. Search endpoint accepts both GET and POST requests. If the size of the request is too large, you may need to use POST\r\nas HTTP GET has a size limit of 2K"
operationId: SearchFoundation
parameters:
- name: q
in: query
description: Text to be searched. Having the character % at the end will be regarded as a wild card for that word
schema:
type: string
- name: subtreesFilter
in: query
description: Optional parameter. Comma separated list of URIs. If provided, the search will be performed on the entities provided and their descendants
schema:
type: string
- name: chapterFilter
in: query
description: Optional, comma or semicolon separated list of chapter codes eg:01;02;21 When provided, the search will be performed only on these chapters
schema:
type: string
- name: useFlexisearch
in: query
description: "Changes the search mode to flexible search.\r\n - In the regular search mode, the Coding Tool will only give you results that contain all of the words that you've used in your search. It accepts different variants or \r\n synonyms of the words but essentially it searches for a result that contains all components of your search. Whereas in flexible search mode, the results do not have to \r\n contain all of the words that are typed. It would still try to find the best matching phrase but there may be words in your search that are not matched at all\r\n - It is recommended to use flexible search only when regular search does not provide a result"
schema:
type: boolean
default: false
- name: flatResults
in: query
description: "Optional parameter. Default value false. If set to true the search result entities are provided in a nested data structure\r\n representing the ICD-11 hierarchy. Otherwise they are listed as flat list of matches"
schema:
type: boolean
default: true
- name: propertiesToBeSearched
in: query
description: "The properties to be searched. By default the system searches, Title, Synonyms and FullySpecifiedName.\r\n The valid values that could be used are: \"Title\", \"Synonym\", \"NarrowerTerm\", \"FullySpecifiedName\", \"Definition\" and \"Exclusion\"\r\n More than one property could be used with \",\" as the separator. In this case the results will include matches from any one of these properties"
schema:
type: string
- name: releaseId
in: query
description: "This is an optional parameter and if ignored, the API will return values from the latest released version of the Foundation.\r\n If provided, the API will respond using that particular release. The values are like 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications"
schema:
type: string
- name: highlightingEnabled
in: query
description: "Optional. Default is true, if set to false the search result highlighting is turned off\r\n and the results don't contain special tags for highlighting where the results are found within the text"
schema:
type: boolean
default: true
- name: API-Version
in: header
description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
required: true
schema:
type: string
- name: Accept-Language
in: header
description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ISearchResult'
'401':
description: Unauthorized
components:
schemas:
AutoCodingSearchResult:
type: object
properties:
searchText:
type: string
description: Text that is searched
nullable: true
matchingText:
type: string
description: The best matching phrase found in the classification
nullable: true
theCode:
type: string
description: Code of the best matching entity found in the classification
nullable: true
foundationURI:
type: string
description: Foundation URI of the best matching entity found in the classification
nullable: true
linearizationURI:
type: string
description: Linearization URI of the best matching entity found in the classification
nullable: true
matchLevel:
$ref: '#/components/schemas/MatchLevelEnum'
matchScore:
type: number
description: Shows the score of the match. The score is a value between 0 and 1. The higher the score the better the match.
format: double
matchType:
$ref: '#/components/schemas/PropertyValueTypeEnum'
isTitle:
type: boolean
additionalProperties: false
description: Response object for autocode endpoint
ISimpleEntity:
type: object
properties:
id:
type: string
description: URI of the Entity
nullable: true
title:
type: string
description: "Title of the Entity. The matched part of the title has a special markup for highlighting. \r\nFor example when searched for the cholera the title Vibrio cholera will be like Vibrio <em class=\"found\">cholera</em>"
nullable: true
stemId:
type: string
description: "If the search result is composed of multiple URIs (i.e. postcoordinated result), Stem Id contains the URI of the stem code\r\nThis field contains the same information as Id in foundation search results"
nullable: true
isLeaf:
type: boolean
description: Shows whether the entity is a leaf node (i.e. does not have any children)
postcoordinationAvailability:
$ref: '#/components/schemas/PostcoordinationAvailabilityEnum'
hasCodingNote:
type: boolean
description: Shows whether there is a coding note attached to the item
hasMaternalChapterLink:
type: boolean
description: Shows whether the entity has maternal chapter link
hasPerinatalChapterLink:
type: boolean
matchingPVs:
type: array
items:
$ref: '#/components/schemas/ISimplePropertyValue'
description: List of property values that match the search string
nullable: true
readOnly: true
propertiesTruncated:
type: boolean
description: Shows if the list of matching property values is truncated as a result of too many maching property values
readOnly: true
isResidualOther:
type: boolean
description: Shows if this entity is an other specified residual category. (Not applicable for foundation search )
readOnly: true
isResidualUnspecified:
type: boolean
description: Shows if this entity is an unspecified residual category. (Not applicable for foundation search )
readOnly: true
chapter:
type: string
description: The chapter code for the entity
nullable: true
readOnly: true
theCode:
type: string
description: The code for the entity (Not applicable for foundation )
nullable: true
readOnly: true
score:
type: number
description: Shows how good is the search result. Higher numbers are better matches. There is no other meaning to this value than its relative value
format: double
readOnly: true
titleIsASearchResult:
type: boolean
description: Shows whether the title of the entity is among the search results
readOnly: true
titleIsTopScore:
type: boolean
description: Shows whether the title is the top scored search result
readOnly: true
entityType:
$ref: '#/components/schemas/EntityTypeEnum'
important:
type: boolean
description: Identifies a very good match. The result matches all words from the search query.
readOnly: true
descendants:
type: array
items:
$ref: '#/components/schemas/ISimpleEntity'
description: Used when the search result is not represented as flat list but rather organized according to ICD hierarchy
nullable: true
readOnly: true
additionalProperties: false
description: SimpleEntity class represents a single ICD Entity in a search result
ISimplePropertyValue:
type: object
properties:
propertyId:
type: string
description: Id of the property
nullable: true
readOnly: true
label:
type: string
description: "Label that matches the search query. The matched part of the label has a special markup for highlighting. \r\nFor example when searched for the cholera the Vibrio cholera will be like Vibrio <em class=\"found\">cholera</em>"
nullable: true
readOnly: true
score:
type: number
description: Score of the match for this particular property value
format: double
readOnly: true
important:
type: boolean
description: Identifies a very good match. The result matches all words from the search query.
readOnly: true
foundationUri:
type: string
description: "Only used when searching a linearization\r\nThe foundation URI in which the property value is located.\r\nThis is filled in only during a linearization search when this property value is coming from an under shoreline entity."
nullable: true
propertyValueType:
$ref: '#/components/schemas/PropertyValueTypeEnum'
additionalProperties: false
description: Represents PropertyValues returned in the search result
EntityTypeEnum:
enum:
- 0
- 1
- 2
type: integer
description: "(0) Real: real entity in the linearization / foundation <br />\r\n(1) UnderShoreLineLogicallyDefined: Entity in the foundation that can be represented as a post-coordination combination in the linearization <br />\r\n(2) PostCoordinationCombination: does not exist in the foundation but can be represented as post-coordination combination"
format: int32
TopLevelFoundation:
type: object
properties:
'@context':
type: string
description: JSON-LD Context for the endpoint
nullable: true
'@id':
type: string
description: unique id for the classification
nullable: true
title:
$ref: '#/components/schemas/LanguageSpecificText'
definition:
$ref: '#/components/schemas/LanguageSpecificText'
child:
type: array
items:
type: string
description: List of top level entities
nullable: true
releaseDate:
type: string
description: Release date
nullable: true
releaseId:
type: string
description: Release identifier for this particular release of the classification
nullable: true
browserUrl:
type: string
description: "ICD Browser is a web site that allows users see the ICD in its hierarchical structure at the same time providing search and post-coordination features.\r\nBrowser URL property provides a direct link to the classification in the WHO's on-line ICD Browser."
nullable: true
availableLanguages:
type: array
items:
type: string
description: All languages provided by the API including the one in pre-release state. All languages available in any of the linearizations are included in the list. For example, a language is listed in here even if it is only availabe in one of the linearizations (e.g. ICF)
nullable: true
supportedLinearizations:
type: array
items:
type: string
description: The linearizations from this foundation.
nullable: true
allReleases:
type: array
items:
type: string
description: Top level URIs for all releases available for the foundation. http://id.who.int/icd/entity is the current version and the others are earlier versions
nullable: true
additionalProperties: false
description: Class representing top level for the foundation
ISearchResult:
type: object
properties:
destinationEntities:
type: array
items:
$ref: '#/components/schemas/ISimpleEntity'
description: List of entities that match the search query
nullable: true
readOnly: true
error:
type: boolean
description: Returns true if an error is occurred during the search
readOnly: true
errorMessage:
type: string
description: Error message if there was an error
nullable: true
readOnly: true
resultChopped:
type: boolean
description: If the search matches too many results, then the result is chopped
readOnly: true
wordSuggestionsChopped:
type: boolean
description: Shows if the word suggestion list is chopped as a result of too many matching words.
readOnly: true
guessType:
$ref: '#/components/schemas/GuessTypeEnum'
uniqueSearchId:
type: string
format: uuid
words:
type: array
items:
$ref: '#/components/schemas/GuessWord'
description: List of word suggestions if the search had includeKeywordResult parameter set to true
nullable: true
readOnly: true
additionalProperties: false
description: Represents the search result. The search result is organized by ICD entities and in each entity we provide matching property values
PropertyValueTypeEnum:
enum:
- 0
- 1
- 2
- 3
type: integer
description: "(0) Real: An index info from a linearization entity <br />\r\n(1) UnderShoreLine: An index entity from an entity under the shoreline<br />\r\n(2) UnderShoreLineLogicallyDefined: An index entity from an entity under the shoreline \r\n and has a logical definition<br />\r\n(3) PostCoordinationCombination: Virtual index entity created by following post-coordination\r\n combinations"
format: int32
FoundationEntity:
type: object
properties:
title:
$ref: '#/components/schemas/LanguageSpecificText'
definition:
$ref: '#/components/schemas/LanguageSpecificText'
longDefinition:
$ref: '#/components/schemas/LanguageSpecificText'
fullySpecifiedName:
$ref: '#/components/schemas/LanguageSpecificText'
diagnosticCriteria:
$ref: '#/components/schemas/LanguageSpecificText'
child:
type: array
items:
type: string
description: List of URIs for the child entities
nullable: true
parent:
type: array
items:
type: string
description: List of URIs for the parent entities
nullable: true
ancestor:
type: array
items:
type: string
description: List of ancestors. Provided only with include=ancestor
nullable: true
descendant:
type: array
items:
type: string
description: List of descendants. Provided only with include=descendant
nullable: true
synonym:
type: array
items:
$ref: '#/components/schemas/Term'
description: List of synonyms for this entity
nullable: true
narrowerTerm:
type: array
items:
$ref: '#/components/schemas/Term'
description: List of narrower terms for this entity
nullable: true
inclusion:
type: array
items:
$ref: '#/components/schemas/Term'
description: List of inclusions for this entity
nullable: true
exclusion:
type: array
items:
$ref: '#/components/schemas/Term'
description: List of exclusions for this entity
nullable: true
browserUrl:
type: string
description: "ICD Browser is a web site that allows users see the ICD in its hierarchical structure at the same time providing search and post-coordination features.\r\nBrowser URL property provides a direct link to the classification in the WHO's on-line ICD Browser."
nullable: true
additionalProperties: false
description: Class representing a foundation entity
GuessTypeEnum:
enum:
- 0
- 1
- 2
type: integer
format: int32
Term:
type: object
properties:
label:
$ref: '#/components/schemas/LanguageSpecificText'
foundationReference:
type: string
description: "In some cases such as in exclusions or index terms, the term itself could be coming from another entity in the classification\r\nIn these cases foundationReference holds the foundation URI for that entity\r\nIndex terms generated from foundation entities that are not located in the linearization have this reference"
nullable: true
linearizationReference:
type: string
description: "In some cases such as in exclusions or index terms, the term itself could be coming from another entity in the classification\r\nIn these cases linearizationReference holds the linearization (or release) URI for that entity"
nullable: true
deprecated:
type: boolean
description: If the term has been deprecated, this flag is set to true
additionalProperties: false
description: Class representing a term with language specific label and optional cross references
MatchLevelEnum:
enum:
- 0
- 1
- 2
- 3
- 4
type: integer
format: int32
GuessWord:
type: object
properties:
label:
type: string
nullable: true
dontChangeResult:
type: boolean
additionalProperties: false
description: Represents a keyword returned as a as a word completion suggestion or as a next word suggestion
LanguageSpecificText:
type: object
properties:
'@language':
type: string
description: Language code for the string
nullable: true
'@value':
type: string
description: Label in the given language
nullable: true
additionalProperties: false
description: Language specific text as used in JSON-LD
PostcoordinationAvailabilityEnum:
enum:
- 0
- 1
- 2
type: integer
format: int32
securitySchemes:
oauth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://icdaccessmanagement.who.int/connect/token
scopes:
icdapi_access: ''