API for Medical Conditions

The medical conditions list was derived from the Regenstrief Institute's Medical Gopher program and contains over 2,400 medical conditions along with ICD-10-CM codes, ICD-9-CM codes, and their associated terms. It also contains an extensive list of full term and word synonyms. This list was used for the NLM's Personal Health Record (PHR) project. For more details on the NLM PHR, please visit https://phr-demo.nlm.nih.gov.

API Demo

The following demo shows how this API might be used with an autocompleter we've developed.

For further experimentation with the autocompleter and this API, try the autocompleter demo page.

API Documentation

API Base URL: https://clinicaltables.nlm.nih.gov/api/conditions/v3/search (+ query string parameters)

This data set may also be accessed through the FHIR ValueSet $expand operation.

In addition to the base URL, you will need to specify other parameters. See the query string parameters section below for details.

Query String Parameters and Default Values

At a minimum, when using the above base URL, you will need to specify the "terms" parameter containing a word or partial word to match.

Parameter NameDefault ValueDescription
terms(Required.) The search string (e.g., just a part of a word) for which to find matches in the list. More than one partial word can be present in "terms", in which case there is an implicit AND between them.
maxList Optional, with a default of 7. Specifies the number of results requested, up to the upper limit of 500. If present but the value is empty, 500 will be used.
qAn optional, additional query string used to further constrain the results returned by the "terms" field. Unlike the terms field, "q" is not automatically wildcarded, but can include wildcards and can specify field names. See the Elasticsearch query string page for documentation of supported syntax.
dfconsumer_nameA comma-separated list of display fields (from the fields section below) which are intended for the user to see when looking at the results.
sfconsumer_name, primary_name, word_synonyms, synonyms, term_icd9_code, term_icd9_textA comma-separated list of fields to be searched.
cfkey_idA field to regard as the "code" for the returned item data.
efA comma-separated list of additional fields to be returned for each retrieved list item. (See the Output format section for how the data for fields is returned.) If you wish the keys in the returned data hash to be something other than the field names, you can specify an alias for the field name by separating it from its field name with a colon, e.g., "ef=field_name1:alias1,field2,field_name3:alias3,etc. Note that not every field specified in the ef parameter needs to have an alias.

Medical Conditions Field Descriptions

FieldField Description
primary_nameThe name of the medical condition.
consumer_nameA more consumer-friendly version of the disease name in the primary_name field.
key_idA unique idenitifier (a code) for the medical condition
icd10cm_codesA comma-separated list of suggested ICD-10-CM codes for the condition. Note that some of the ICD10CM codes may have a trailing question mark. In the SNOMED to ICD-10-CM mapping, question marks are used as placeholders for episode in case of injury codes like T code or S code, since there is no episode information in SNOMED concepts. When coding the patients data, the user will need to replace the question marks with episode codes like A,....S if the information is available in the patients' records
icd10cmAn list of code and display name pairs for the suggested ICD-10-CM codes for the condition. When requested with the "ef" parameter, this will be an array of objects, where each object will have "code" and "text" properties. Note that some of the ICD10CM codes may have a trailing question mark, see "icd10cm_codes" above for more details.
term_icd9_codeThe ICD-9-CM code for the term.
term_icd9_textThe ICD-9-CM display text for the term.
word_synonymsSynonyms for each of the words in the term.
synonymsSynonyms for the whole term.
info_link_dataLinks to information about the condition. The returned data is an array of arrays. There is one inner array for each available link about the condition, and each inner array contains the link and the linked page's title (which is useful if you are displaying the list of links for the user to pick one).

Output format

Output for an API query is an array of the following elements:

  1. The total number of results on the server (which can be more than the number returned). For APIs in which there are millions of records, this number might be a lower bound due to early termination if there are more than a hundred thousand results.
  2. An array of codes for the returned items. (This is the field specified with the cf query parameter above.)
  3. A hash of the "extra" data requested via the "ef" query parameter above. The keys on the hash are the fields (or their requested aliases) named in the "ef" parameter, and the value for a field is an array of that field's values in the same order as the returned codes.
  4. An array, with one element for each returned code, where each element is an array of the display strings specified with the "df" query parameter.
  5. An array, with one element for each returned code, where each element is the "code system" for the returned code. Note that only code-system aware APIs will return this array.

Sample API Queries

QueryResultDescription
https://clinicaltables.nlm.nih.gov/api/conditions/v3/search?terms=gastroenteri&df=term_icd9_code,primary_name[9,["4458","18966","8536","11065","2565","1510","4575"],null,[["558.9","Gastroenteritis"],[null,"Viral Enteritis"],["558.9","Colitis"], ["558.9","Inflammatory bowel disease"],["558.9","Ileitis"],["003.0","Salmonella enteritidis"],["558.9","Colitis?"]]]Returns a complete count of the 9 medical conditions that have synonyms that match the string "gastroenteri", displaying both the IDC-9-CM code and the associated consumer_name for the first 7 terms.
https://clinicaltables.nlm.nih.gov/api/conditions/v3/search?terms=gastroenteritis&sf=consumer_name&ef=term_icd9_code,term_icd9_text [1,["4458"],{"term_icd9_code":["558.9"],"term_icd9_text":["Other and unspecified noninfectious gastroenteritis and colitis"]},[["Gastroenteritis"]]] Returns the unique key_id of the term "Gastroenteritis" along with the ICD-9-CM code and ICD-9-CM text that maps to the medical condition with the consumer_name "Gastroenteritis".