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".
This service is provided "as is" and free of charge. Please see the Frequently Asked Questions page for more details on terms of service, etc.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:
- For questions: https://clinicaltables.nlm.nih.gov/api/loinc_items/v3/search?type=question (+ query string parameters)
- For forms: https://clinicaltables.nlm.nih.gov/api/loinc_items/v3/search?type=form&available=true (+ query string parameters)
- For forms and sub-sections of forms:
https://clinicaltables.nlm.nih.gov/api/loinc_items/v3/search?type=form_and_section&available=true
(+ query string parameters)
Here a section is a LOINC item that does not have its own form definition but appears as sections in some other form definitions.
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.
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:
- https://clinicaltables.nlm.nih.gov/loinc_answers?loinc_num=[LOINC_NUM]
(Example: https://clinicaltables.nlm.nih.gov/loinc_answers?loinc_num=45592-3)
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:
- https://clinicaltables.nlm.nih.gov/loinc_form_definitions?loinc_num=[LOINC_NUM]
(Example: https://clinicaltables.nlm.nih.gov/loinc_form_definitions?loinc_num=34565-2)
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 Name | Default Value | Description |
|---|---|---|
| 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 | 7 | 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. Note that this parameter does not support pagination, see "count" and "offset" below for details on pagination support. |
| count | 7 | The number of results to retrieve (page size). The maximum count allowed is 500, see "offset" below on pagination support. |
| offset | 0 | The starting result number (0-based) to retrieve. Use offset and count together for pagination. Note that the current limit on the total number of results that can be retrieved (offset + count) is 7,500. We reserve the right to decrease or increase this limit based on system capacity and/or other factors. Please see the FAQ page on how to sign up to our email list to be notified of any changes or new features. |
| q | An 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. | |
| excludeCopyrighted | false | Set this to "true" to exclude forms and questions that either are copyrighted or contain a coprighted item. |
| type | Can be one of: "question", to limit the search to questions; or "form", to limit the search to forms; or "panel", to limit the search to all panels. Without this parameter, both questions and panel names will be searched simultaneously. | |
| available | Set 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.) | |
| df | text | A comma-separated list of display fields (from the fields section below) which are intended for the user to see when looking at the results. |
| sf | text, COMPONENT, CONSUMER_NAME, RELATEDNAMES2, METHOD_TYP, SHORTNAME, LONG_COMMON_NAME, LOINC_NUM | A comma-separated list of fields to be searched. |
| cf | LOINC_NUM | A field to regard as the "code" for the returned item data. |
| ef | A 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.
| Field | Field Description |
|---|---|
| text | The text of the question or form name. This is determined algorithmically by looking at various LOINC fields. |
| LOINC_NUM | The LOINC code for the question or form. |
| RELATEDNAMES2 | Contains word-level synonyms. |
| PROPERTY | LOINC property |
| METHOD_TYP | LOINC method type |
| AnswerLists | While most questions have a single answer list without applicable context(s) specified, some questions may have multiple answer lists each for a different set of applicable contexts. This field represents the answer lists (single or multiple) with the corresponding applicable contexts specified within each answer list. |
| units | For 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. |
| datatype | A 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. |
| isCopyrighted | This 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. IMPORTANT: this field is indexed as a boolean field and can thus be used in the "q" parameter for filtering. It's marked as "not searchable" in the sense that you can't perform autocomplete (search) on this field itself, that is, it can not be used in the "sf" parameter. |
| containsCopyrighted | This 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. IMPORTANT: this field is indexed as a boolean field and can thus be used in the "q" parameter for filtering. It's marked as "not searchable" in the sense that you can't perform autocomplete (search) on this field itself, that is, it can not be used in the "sf" parameter. |
| CONSUMER_NAME | Along with LONG_COMMON_NAME, SHORTNAME, and COMPONENT, this is one of the alternatives for the text of the question or form name. |
| LONG_COMMON_NAME | Along with CONSUMER_NAME, SHORTNAME, and COMPONENT, this is one of the alternatives for the text of the question or form name. |
| SHORTNAME | Along with CONSUMER_NAME, LONG_COMMON_NAME, and COMPONENT, this is one of the alternatives for the text of the question or form name. |
| COMPONENT | Along 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_NOTICE | For questions or forms that have additional copright beyond the LOINC copyright, this field contains the copyright notice. |
| EXTERNAL_COPYRIGHT_LINK | This is a short identifier for the external copyright notice. |
Output format
Output for an API query is an array of the following elements:
- The total number of results on the server, which can be more than the number of results returned. This reported total number of results may also be significantly less than the actual number of results and is limited to 10,000, which may significantly improve the service response time.
- An array of codes for the returned items. (This is the field specified with the cf query parameter above.)
- 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.
- 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.
- 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
| Query | Result | Description |
|---|---|---|
| https://clinicaltables.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://clinicaltables.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://clinicaltables.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). |