UCUM Web Service

This is a set of web services (APIs) for programs to use when working with units from the Unified Code for Units of Measure (UCUM) system. These are the same APIs as those that are running at xml4pharmaserver.com, and were originally (and still partially) based on that website's web service code which has been donated to the U.S. National Library of Medicine by FH-Prof. Jozef Aerts and Mr. Milos Ilic MSc, Institute of eHealth, University of Applied Sciences FH Joanneum in Graz Austria.

Currently, three web services are available:

General notes:

UCUM Service version: 3.1.3 (changes)

Introduction

Through the UCUM "ucum-essence.xml" file it is possible to do unit conversions without the need of conversion tables.
An algorithm has been developed that takes any unit in UCUM notation and decomposes it (using "cascading") into the base units (m,s,g,rad,K,cd,rad,mol), allowing one to do unit conversion calculations.
This algorithm has now also been implemented in this RESTful web service. It is also used to validate whether a string corresponds to a valid UCUM unit (i.e. is a valid UCUM notation).

Note: Please see the notes and disclaimers below before using this service in production.

UCUM Unit Conversion web service

The principles of the web service are the following:

So the HTTP request format is essentially:
/{source_quantity}/from/{source_unit}/to/{target_unit}
or:
/from/{source_unit}/to/{target_unit}
when the source quantity = 1 (the default)

Depending on what requested MIME type your HTTP request has (XML, JSON, text), you will receive either XML, JSON or simple text.
In the latter case, you will get a simple string like:

1.0 [in_i] = 2.54 cm

To select between XML, JSON, and text output, one specifies an "Accept" header in the HTTP request, i.e., "Accept: application/xml", "Accept: application/json", or "Accept: text/plain". The default output is in XML, which for this example provides the structure below.


<UCUMWebServiceResponse ServerDateTime="2017-12-26T20:15:48">
  <WebServiceRequest>https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/120/from/mm%5BHg%5D/to/kg/(m.s2)</WebServiceRequest>
  <Response>
    <SourceQuantity>120.0</SourceQuantity>
    <SourceUnit>mm[Hg]</SourceUnit>
    <TargetUnit>kg/(m.s2)</TargetUnit>
    <ResultQuantity>15998.64</ResultQuantity>
  </Response>
</UCUMWebServiceResponse>

Simple examples (all for request type "text")

To convert 1 inch (UCUM notation [in_i]) to centimeter (cm), use:
https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/1/from/[in_i]/to/cm
or: https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/from/[in_i]/to/cm
(as 1 is the default for the value to be converted).
Result: 1.0 [in_i] = 2.54 cm

To convert 3.5 foot (UCUM notation [ft_i] to micrometer (um), use:
https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/3.5/from/[ft_i]/to/um
Result: 3.5 [ft_i] = 1066800.0 um

To convert 1 apothecary ounces (UCUM notation: [oz_ap]) to grams (g), use:
https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/from/[oz_ap]/to/g
Result: 1.0 [oz_ap] = 31.103477 g

To convert 2.5 pounds per square inch (UCUM notation: [psi]) into millimeter mercury column (UCUM notation: mm[Hg]) use:
https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/2.5/from/[psi]/to/mm[Hg]
Result: 2.5 [psi] = 129.28769 mm[Hg]


Somewhat more difficult examples

Suppose you have a flow rate expressed in US gallons per minutes (UCUM notation: [gal_us]/min), and want to convert that to liters per hour (UCUM notation: l/h or L/h - both are valid). Use:
https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/1/from/[gal_us]/min/to/l/h
Result: 1.0 [gal_us]/min = 227.12471 l/h

In order to convert "millimeter of mercury" (UCUM notation mm[Hg]) into its base components, which is kg/m.s-2 (kilogram per meter times square seconds), use:
https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/1/from/mm[Hg]/to/kg/m.s-2
Result: 1.0 mm[Hg] = 133.322 kg/m.s-2


Non-matching properties

When trying to convert between units for which the properties don't match (e.g. weight to time), you will get an error message.
For example for kg (kilograms) to min (minutes), when you use:
https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/1/from/kg/to/min
you will get the error message: Error: Source and Target unit do not seem to belong to the same property
Properties must also match for complex expressions (e.g., kg/m.s-2), for which the converting engine breaks the expression down to the base units, and compares the exponents on the base units between source and target.


Conversions using moles

This section is about conversions where "mol" appears in both the target and soure unit. For conversions from mol to other types of units, see below.

Essentially, "mol" is not a unit, it is a number. So 1 mol of cows is 6.022E23 cows.
However, as people are used to working with mole as if it were a unit, "mol" was implemented as a base unit. So if, for example, we want to do a concentration conversion such as "convert 1 mol per cubic inch (UCUM notation: [in_i]3) to mol/L", we use:
https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/1/from/mol/[in_i]3/to/mol/L
Result: 1.0 mol/[in_i]3 = 61.023744 mol/L

One can also do more complex unit conversions using "mol", such as between "PK units" that have been published by CDISC
For example, if you want to do the conversion between "h.pmol/l" (picomol-hours per liter) to "min.umol/ml" (micromol-minutes per cubic meter), use:
https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/1/from/h.pmol/l/to/min.umol/m3
Result: 1.0 h.pmol/l = 0.06 min.umol/m3
This works, as both "l" (liter) and "m3" are volumes.


Conversions between moles, mass, and equivalents

Conversions between units involving moles, mass, and equivalents ("eq") can be done with some limitations:

For mass-mole conversions when the molecular weight is known, include it at the end of the URL, after "MOLWEIGHT", like:
https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/1/from/mg/dL/to/mmol/L/MOLWEIGHT/180.156

For mass-mole conversions when the the LOINC code is known, include it at the end of the URL, after "LOINC", like:
https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/1/from/mg/dL/to/mmol/L/LOINC/2339-0

For conversions between equivalents and either mass or moles, also supply the LOINC code at the end, as above. For example:
https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/1/from/meq/L/to/mmol/L/LOINC/49765-1


One can also use parentheses (but no nested parentheses yet), for example:

https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/1/from/m/(mg2.s2)/to/m.s-2.g-2


Annotations

In some cases, you might want to use annotations, for example to express "mol of creatinine".
You can do so, as long as there is a match between the annotations of the source with the annotations at the target side. If this is not the case, you will obtain an error message saying: ERROR: annotations mismatch between source and target

A valid web service request is, for example:
https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/1/from/mol{creatinine}/l/to/mol{creatinine}/[in_i]3
Result: 1.0 mol{creatinine}/l = 0.016387064 mol{creatinine}/[in_i]3


UCUM for SEND

(The following example is courtesy of Jozef Aerts of XML4Pharma.)

One of the misconceptions (within CDISC) about UCUM is that it would not be useful for units of the preclinical world (such as CDISC-SEND submissions). The contrary is true! UCUM brings order in units for animal and other preclinical studies. For example for the CDISC "PKUNIT" codelist (NCI C85494) contains almost 300 terms, with CDISC adding new ones each time a new version is published. As the number of combinations is in principle inifinite, this list will grow and grow.
Furthermore, the CDISC codelist does not provide a mechanism for unit conversions. It does not, for example, allow one to calculate how many "(L/h)/m2" go into "(L/min)/cm2".
For "PKUNIT", no codelist is necessary: UCUM solves everything!

Let us take a somewhat more typical SEND example: We have chickens that drink water, and measure how much water they consume as function of the amount of space they have, amount of food, and time.
We however have one group in the US that measures this using gallons, square feet, ounces of food, and hours. In Europe however, the same measurement is made using liters, square meters, grams of food, and days.
With UCUM, this would be expressed as:

UCUM notation for the measurement in the US: [us_gal]{waterconsumption}/([ft_i]2.{chicken}.[oz_av]{food}.h)
UCUM notation for the measurement in Europe: l{waterconsumption}/(m2.{chicken}.g.{food}.d)

The conversion factor can easily be obtained using our RESTful web service:

https://ucum.nlm.nih.gov/ucum-service/v1/ucumtransform/from/l{waterconsumption}/(m2.{chicken}.g{food}.d)/to/[gal_us]{waterconsumption}/([ft_i]2.{chicken}.[oz_av][food].h)

Current limitations

Currently we still have following limitations (but are working on removing them):

If you find any other limitations or errors, please contact us.

The UCUM unit validity service

In some cases you (or your application) simply wants to check whether a string corresponds to a valid UCUM string/unit.
This can easily be done by using the "isValidUCUM" web service.

This web service is very simple to use:

Because the output is so simple, there are no alternative formats (XML and JSON) for this service, unlike the others.

Examples:

The UCUM unit to base units service

Request string:
https://ucum.nlm.nih.gov/ucum-service/v1/toBaseUnits/{unit}

For example, if you don't know the base units of "circular mil" (UCUM notation "[cml_i]"), you submit:
https://ucum.nlm.nih.gov/ucum-service/v1/toBaseUnits/[cml_i]

Or for "gallon per square foot":
https://ucum.nlm.nih.gov/ucum-service/v1/toBaseUnits/[gal_us]/[sft_i]

Result:


<UCUMWebServiceResponse ServerDateTime="2017-12-26T23:05:32">
  <WebServiceRequest>https://ucum.nlm.nih.gov/ucum-service/v1/toBaseUnits/%5Bgal_us%5D/%5Bsft_i%5D</WebServiceRequest>
  <Response>
    <SourceUnit>[gal_us]/[sft_i]</SourceUnit>
    <ResultBaseUnits>m</ResultBaseUnits>
    <ResultQuantity>0.040745833</ResultQuantity>
    <ResultBaseUnitsList>
      <BaseUnit Name="m" Exponent="1"/>
    </ResultBaseUnitsList>
  </Response>
</UCUMWebServiceResponse>

When you think about it, it is clear: "gallon" is a volume (base unit: m3) and "square foot" is an area (base unit: m2), so, "gallon per square foot" reduces to "m" (exponent=1) and the "conversion" factor is 0.0407.

Output can also be requested in JSON or a plain text format, again by specifying an "Accept" header in the HTTP request, as mentioned above.

Another example is breaking down mm[Hg] to the base units:

https://ucum.nlm.nih.gov/ucum-service/v1/toBaseUnits/mm[Hg]

Which returns (here as XML):


<UCUMWebServiceResponse ServerDateTime="2017-12-26T23:08:27">
  <WebServiceRequest>https://ucum.nlm.nih.gov/ucum-service/v1/toBaseUnits/mm%5BHg%5D</WebServiceRequest>
  <Response>
    <SourceUnit>mm[Hg]</SourceUnit>
    <ResultBaseUnits>s-2.g.m-1</ResultBaseUnits>
    <ResultQuantity>133322.0</ResultQuantity>
    <ResultBaseUnitsList>
      <BaseUnit Name="s" Exponent="-2"/>
      <BaseUnit Name="g" Exponent="1"/>
      <BaseUnit Name="m" Exponent="-1"/>
    </ResultBaseUnitsList>
  </Response>
</UCUMWebServiceResponse>

Essentially stating that 1 mm[Hg] = 133322 g.s-2.m-1 (in UCUM notation, or 133322 g/(m*s2) using standard operator symbols).

Also, note that the entries under "ResultBaseUnitList" can be used for easily treating the result or for chaining

Note on special units: For "special" UCUM units, which are units that require some formula to be converted to base units (such [degF] to K), the result quantity is not included to avoid the misunderstaning that it could be used as a scaling factor for converting other amounts of the source unit. Also, for the plain text output format, the normal '=' sign between the source and base unit string is replaced with '~', for the same reason.

Special character encoding

 Not all browsers correctly encode the special characters "[", "]", "{" and "}" when doing the HTTP request. So if you copy-paste the listed URLs, you may need to replace following special characters: In applications, this might be taken care of by the framework that you use (e.g. JAX-RS), but if not, look for an API that will "URL encode" the unit strings.

When using the browser, also ensure that it accepts XML, and displays it as such, i.e. that it does not try to "style" it. For example, some issues have been reported with Firefox with the Skype plugin.

Use of these web services and disclaimers

 Although one can use these web services in the browser, this is not the primary use of RESTful web services. This kind of web service is meant to be used in applications.

You are invited to use these web services in your pilot and production applications, taking the following into account:

If you find any bugs or would like to comment on these services or have suggestions, please contact us.