API for LOINC Questions and Forms

LOINC is a universal code system for medical tests and measurements. The tests (hereafter referred to as "questions") are themselves coded and may have coded answer lists. Questions are in some cases organized into forms, such as a vital signs form with questions for height, weight, blood pressure, etc. This API provides a means of looking up LOINC questions or forms, and for retrieving a question's answer list or a form's definition, which can then be rendered in a web page by the LHC-Forms widget.

Important Copyright Information

The LOINC codes are copyrighted by Regenstrief Institute, and users of this API must agree to the LOINC Terms of Use. Additionally, some of the LOINC terms have further copyrights, and use of those terms must comply with those copyright notices. The copyright notices for individual terms are available in the field "EXTERNAL_COPYRIGHT_NOTICE" (see below) which can be retrieved with the "ef" parameter. To aid in determining which fields in a list of search results from this API have something in EXTERNAL_COPYRIGHT_NOTICE, we have added two fields, isCopyrighted and containsCopyrighted (which is true if either the item itself or a contained item has isCopyrighted set to "true"). It should be noted that isCopyrighted being false only refers to the external copyright; all records are still subject to LOINC's copyright.

If you wish to exclude records for which there is an external copyright, you can set the "excludeCopyrighted" parameter to "true".

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.

We also have a demo showing how to retrieve and render a form definition.

API Documentation

Search API Base URL:

If for some reason you want to search both questions and forms simulatenously, you can also leave off the "type" parameter.

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

Retrieving answer lists for list questions:
Using the Search API Base URL above for questions (with the appropriate parameters from the query string parameters section below), will return one or more codes (along with the question text). To get answer lists for questions that have lists, use the following, replacing "[LOINC_NUM]" with the code:

Retrieving form definitions:
Using the Search API Base URL above for forms (with the appropriate parameters from the query string parameters section below), will return one or more codes (along with the form names). To get form definitions for those forms, use the following, replacing "[LOINC_NUM]" with the code:

As noted above, retrieved form definitions can be rendered with the LHC-Forms display widget. See the form demo for an example for how do that.

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.
excludeCopyrightedfalseSet this to "true" to exclude forms and questions that either are copyrighted or contain a coprighted item.
typeSet to "question" to limit the search to questions or to "form" to limit the search to forms. Without this parameter, both questions and form names will be search simultaneously.
availableSet to "true" to limit a search on forms to those for which we can return the form definitions via /loinc_form_definitions API. If you leave this blank, a few of the returned forms might not have a definition via our API. (If you set it to false, you will only get the forms for which we do not have definitions, which is probably not a useful thing to do.)
dftextA comma-separated list of display fields (from the fields section below) which are intended for the user to see when looking at the results.
sftext, COMPONENT, CONSUMER_NAME, RELATEDNAMES2, SHORTNAME, LONG_COMMON_NAME, LOINC_NUMA comma-separated list of fields to be searched.
cfLOINC_NUMA 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.

LOINC API Field Descriptions

These are the available field names for searching and/or retrieving.

FieldField Description
textThe text of the question or form name. This is determined algorithmically by looking at various LOINC fields.
LOINC_NUMThe LOINC code for the question or form.
RELATEDNAMES2Contains word-level synonyms.
PROPERTYLOINC property
answersFor questions that have answers, listing this field in the "ef" parameter list will cause the answer list to be returned along with the questions. However, you can also retrieve the answers for an individual question via the /loinc_answers API above. This field is not searchable, i.e., it cannot be used with the sf parameter.
unitsFor questions with numeric values, this is list of UCUM-style units. Each element in the array is a hash with keys "unit" for the UCUM unit symbol and (for a few) "range" for the normal range of the value in that unit. These come from the UnitsAndRange and the EXAMPLE_UCUM_UNITS columns of the LOINC "panels and forms" spreadsheet. This field is not searchable, i.e., it cannot be used with the sf parameter.
datatypeA computed data type for the question, derived from various other fields. Values can be "CNE" (for a question whose answer must come from a list), "CWE" (for a question whose answer can be from a list but can also be an answer that is not on the list), "ST", for a normal text field, "REAL" for numeric fields, "DT" for date fields, "TM" for time fields, and "Ratio" for titers.
isCopyrightedThis will be true if the item has an external copyright, in which case you will be able to find the copyright notice in the EXTERNAL_COPYRIGHT_FIELD. Note that even when this is false, there is still a copyright held by Regenstrief Institute, and users of this API must agree to the LOINC Terms of Use.
containsCopyrightedThis will be true if isCopyrighted is true either for this item or for a contained item. For example, if a form is not itself copyrighted, but contains a copyrighted question, this will be true while isCopyrighted will be false. Note that even when this is false, there is still a copyright held by Regenstrief Institute, and users of this API must agree to the LOINC Terms of Use.
CONSUMER_NAMEAlong with LONG_COMMON_NAME, SHORTNAME, and COMPONENT, this is one of the alternatives for the text of the question or form name.
LONG_COMMON_NAMEAlong with CONSUMER_NAME, SHORTNAME, and COMPONENT, this is one of the alternatives for the text of the question or form name.
SHORTNAMEAlong with CONSUMER_NAME, LONG_COMMON_NAME, and COMPONENT, this is one of the alternatives for the text of the question or form name.
COMPONENTAlong with CONSUMER_NAME, LONG_COMMON_NAME, and SHORTNAME, this is one of the alternatives for the text of the question or form name.
EXTERNAL_COPYRIGHT_NOTICEFor questions or forms that have additional copright beyond the LOINC copyright, this field contains the copyright notice. This field is not searchable, i.e., it cannot be used with the sf parameter.
EXTERNAL_COPYRIGHT_LINKThis is a short identifier for the external copyright notice. This field is not searchable, i.e., it cannot be used with the sf parameter.

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://clin-table-search.lhc.nlm.nih.gov/api/loinc_items/v3/search?type=question&terms=walk&ef=isCopyrighted [165,["45593-1","52654-1","54751-3","52671-5","41953-1","41957-2", "63865-0"],{"isCopyrighted":[true,false,false,false,false,false,false]},[["Walk in room - support provided"],["Walk 100 ft (30 m) during 2D assessment period"],["Turning around and facing the opposite direction while walking in last 7D"],["Walking 10 feet on uneven surfaces during 2D assessment period"],["Walk distance 24h Calc"],["Walking Speed 24h Mean Calc"],["Moderate exercise Hs PhenX"]]] Returns 7 of 165 total questions containing terms starting with "walk" as a JSON string. LOINC_NUM is being returned for the codes, and the "text" field is being returned for the question text.
https://clin-table-search.lhc.nlm.nih.gov/api/loinc_items/v3/search?ef=EXTERNAL_COPYRIGHT_NOTICE&terms=45593-1 [1,["45593-1"],{"EXTERNAL_COPYRIGHT_NOTICE":["InterRAI holds the copyright to ..."]},[["Walk in room - support provided"]]] This is an example of how to retrieve an external copyright notice for a given LOINC term (in this case the term for code "45593-1". Only the first part of the copyright notice is shown here; the complete notice would be returned in the actual results.
https://clin-table-search.lhc.nlm.nih.gov/loinc_answers?loinc_num=45592-3 [{"AnswerStringID":"LA12637-7","DisplayText":"Independent - no help or staff oversight at any time","SequenceNo":1,"Score":0},{"AnswerStringID":"LA12638-5","DisplayText":"Supervision - oversight, encouragement or cueing","SequenceNo":2,"Score":0},{"AnswerStringID":"LA12639-3","DisplayText":"Limited assistance - resident highly involved in activity; staff provide guided maneuvering of limbs or other non-weight-bearing assistance","SequenceNo":3,"Score":0},{"AnswerStringID":"LA12640-1","DisplayText":"Extensive assistance - resident involved in activity, staff provide weight-bearing support","SequenceNo":4,"Score":0},{"AnswerStringID":"LA12641-9","DisplayText":"Total dependence - full staff performance every time during entire 7-day period","SequenceNo":5,"Score":0},{"AnswerStringID":"LA12642-7","DisplayText":"Activity occurred only once or twice - activity did occur but only once or twice","SequenceNo":6,"Score":0},{"AnswerStringID":"LA18614-0","DisplayText":"Activity did not occur - activity did not occur or family and/or non-facility staff provided care 100% of the time for that activity over the entire 7-day period","SequenceNo":7,"Score":0}] Returns the answers for the question whose code is 45592-3 ("Walk in room - self-performance"). Each answer contains a code ("AnswerStringID") and text ("DisplayText"), as well as a sequence number ("SequenceNo") for ordering the answers, and a score (which in this case is set to 0 for all answers because it is not used).