API for UCUM (The Unified Code for Units of Measure)

The Unified Code for Units of Measure (UCUM), according to its website, is "a code system intended to include all units of measures being contemporarily used in international science, engineering, and business. The purpose is to facilitate unambiguous electronic communication of quantities together with their units."

For this API, the data from the UCUM website has been extended with commonly used combinations of UCUM units found in LOINC, and LOINC properties have been added to UCUM records.

In addition to this API for searching within UCUM, we also have several other UCUM resources.

Important Copyright Information: Note that use of UCUM is subject to Terms of Use.

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/ucum/v3/search (+ query string parameters)

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.
dfcs_code, 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.
sfcs_code, name, synonyms, cs_code_tokensA comma-separated list of fields to be searched.
cfcs_codeA 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.

UCUM Field Descriptions

FieldField Description
cs_codeThe unique, case-sensitive code of the unit, e.g, kg.
nameThe name of the unit, e.g, kilogram.
categoryThe category of the unit, which can be one of: Clinical, Nonclinical, Constant, or Obsolete.
synonymsSynonyms of the unit.
loinc_propertyThe LOINC property of the unit, e.g., Mass, MRat.
guidanceThe description of the unit, if any.
sourceThe source of the unit, which can be either UCUM or LOINC.
is_simpleThis field indicates if the unit is a simple unit (without operators). The value can be either true or false. 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.
cs_code_tokensThe same as the cs_code field except that it's indexed in a different way to improve search recall. It's meant for use as a search field only.

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/ucum/v3/search?terms=kg [56,["kg","kg/L","kg/h","kg/mol","kg/m2","kg/min","kg/s"],null,[["kg","kilogram"],["kg/L","kilogram per liter"],["kg/h","kilogram per hour"],["kg/mol","kilogram per mole"],["kg/m2","kilogram per square meter"],["kg/min","kilogram per minute"],["kg/s","kilogram per second"]]] Returns a list of 7 (out of 56 total) UCUM units codes and names that match (or start with) "kg".
https://clinicaltables.nlm.nih.gov/api/ucum/v3/search?terms=ml&ef=loinc_property [62,["mL","[drp]","mL/min","mL/kg","mL/dL","mL/mbar","mL/(4.h)"],{"loinc_property":["Vol","Vol","VRat","VCnt","VFr; VFrDiff","","VRat"]},[["mL","milliliter"],["[drp]","drop - metric (1/20 mL)"],["mL/min","milliliter per minute"],["mL/kg","milliliter per kilogram"],["mL/dL","milliliter per deciliter"],["mL/mbar","milliliter per millibar"],["mL/(4.h)","milliliter per 4 hour"]]] Returns a list of 7 (out of 66 total) UCUM units codes and names that match (or start with) "ml". Note that the "ef=loinc_property" parameter caused the loinc_property field to be returned as well.