The XML4Pharma Application Server

XML4Pharma UCUM unit Web Services

Currently, two web services are available:


Introduction

Through the "ucum-essence.xml" file it is possible to do unit conversions without the need of conversion tables.
We have developed an algorithm 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 to do unit conversion calculations.
This algorithm has now also been implemented in a 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).


UCUM Unit Conversion web service

Through the "ucum-essence.xml" file it is possible to do unit conversions without the need of conversion tables.
We have developed an algorithm 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 to do
unit conversion calculations.
This algorithm has now also been implemented in a 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).

ATTENTION: 2016-09-10: API change!

The principles of the web service are the following:

So the HTTP request format is essentially:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/{source_quantity}/from/{source_unit}/to/{target_unit}
or:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/from/{source_unit}/to/{target_unit}
when the source quantity = 1 (the default)

Depending on what 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

In case your HTTP request is for XML, you will get the information according to the following structure:

Simple examples (all for request type "text")

To convert 1 inch (UCUM notation [in_i]) to centimeter (cm), use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/[in_i]/to/cm
or: http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/from/[in_i]/to/cm
(as 1 is the default for the value to be converted) Resulting in: 1.0 [in_i] = 2.54 cm

To convert 3.5 foot (UCUM notation [ft_i] to micrometer (um), use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/3.5/from/[ft_i]/to/um
Resulting in: 3.5 [ft_i] = 1066800.0 um
the "0002" at the end being caused by the cascading algorithm.

To convert 1 apothecary ounces (UCUM notation: [oz_ap]) to grams (g), use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/from/[oz_ap]/to/g
Resulting into: 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:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/2.5/from/[psi]/to/mm[Hg]
Resulting in: 2.5 [psi] = 129.28769 mm[Hg]

Somewhat more difficult examples

Suppose you have a low 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), then use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/[gal_us]/min/to/l/h
Resulting in: 1.0 [gal_us]/min = 227.12471 l/h

In order to convert millimeter mercury column (UCUM notation mm[Hg]) into its base components, which is kg/m.s-2 (kilogram per meter times square seconds), use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/mm[Hg]/to/kg/m.s-2
Resulting in: 1.0 mm[Hg] = 133.322 kg/m.s2

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:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/kg/to/min
This results in the error message: Error: Source and Target unit do not seem to belong to the same property
This will also work for more complex expressions, as the converting engine breaks the unit down to the base units, and compares the exponents on these between source and target.

Conversions using moles

Essentially, "mol" is not a unit, it is a number. So 1 mol of cows is 6.023E23 number of cows (I don't believe we have one mol of cows on earth...).
However, as people are used to work with moles as if it were a unit, we implemented "mol" as being a base unit. So if we want to e.g. do a concentration conversion, like:
convert 1 mol per cubic inch (UCUM notation: [in_i]3) to mol/L, we use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/mol/[in_i]3/to/mol/L
Resulting in: 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, you want to do the conversion between "h.pmol/l" (picomol-hours per liter) to "min.umol/ml" (micromol-minutes per cubic meter), use:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/h.pmol/l/to/min.umol/m3
Resulting in: 1.0 h.pmol/l = 0.06 min.umol/m3
This works, as both "l" (liter) as "m3" are volumes.

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

http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/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 however e.g.:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/mol{creatinine}/l/to/mol{creatinine}/[in_i]3
Resulting in: 1.0 mol{creatinine}/l = 0.016387064 mol{creatinine}/[in_i]3

Complicated examples

This example was inspired by the CDISC-CT "PKUNIT" codelist, which has been developed for pharmacokinetic measurements. This codelist does not allow to do any unit conversions at all.

Suppose that site A (in Europe) has measured a pharmacokinetic parameter on animals (in this case chickens) as part of a pre-clinical study (for a CDISC SEND submission), in the units:
international units per mg of drug (named "supercompund) per (g per kilogram of chicken per hour)
and another site B (in the US) has measured the same property but in the units:
milli-iternational units per ounce of drug per (gram per pound of of chicken per day)
Than the conversion factor between both can be obtained from the web service using:
http://www.xml4pharmaserver.com:8080/CDISCCTService/rest/ucumtransform/1/from/[iU]/mg{supercompound}/(g/kg{chicken}/h)/to/m[iU]/[oz_av]{supercompound}/(g/[lb_av]{chicken}/d)

Want to know the answer? Then try it yourself!

Current limitations

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

If you find any other limitations or errors, please report them


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:

examples


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 should however be taken care of by the framework that you use (e.g. JAX-RS).

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

Although one can use these web services in the browser (you probably already discovered that), this is not the primary use of RESTful web services. This kind of web services is meant to be used in applications, such as already have been done in the "Smart Dataset-XML Viewer", an open source viewer for CDISC SDTM/SEND/ADaM submissions in XML available from SourceForge.

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

Courtesy of XML4Pharma - last update: August 2015