|
|
The NLM UCUM web services are described at: https://ucum.nlm.nih.gov/ucum-service.html
As the transfer is now complete, we will undeploy our own UCUM RESTful web services by end October 2020.
Please ensure to adapt your applications using this service by that time!
The API for the UCUM services on the NLM server is almost 100% identical to ours which is described below.
In order to adapt your client applications, all you need to do it to change the base of the service from:
http://www.xml4pharmaserver.com:8080/UCUMService/rest/ to https://ucum.nlm.nih.gov/ucum-service/v1/
The response of the NLM UCUM web service is identical to ours, with one minor difference:
The root element of the NLM RESTful web service response is UCUMWebServiceResponse, whereas it is XML4PharmaServerWebServiceResponse on our server.
If you would like to have these UCUM services implemented on a company intranet server, please contact us
Currently, the following web services are available:
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).
Later, it was extended to allow conversions between molar concentrations (and other properties using moles) and mass concentrations and vice versa,
either based on the LOINC code of the test, or on a molecular weight of the analyte provided by the user or his/her application.
The latter conversions are also known in clinical research as "SI Units to Conventional Units" and "Conventional Units to SI Units" conversions, currently causing great problems in electronic submissions to the FDA.
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: 2017-11-04: Base of the service changed
As UCUM has nothing to do with CDISC-CT (yet), we changed the base of the service from http://www.xml4pharmaserver.com:8080/CDISCCTService/ to
http://www.xml4pharmaserver.com:8080/UCUMService/. We will however keep the older version of the service available until we are sure that (almost) nobody
is using it anymore. To be sure, and if you read this, please change the base of the service in your software.
The principles of the web service are the following:
So the HTTP request format is essentially:
http://www.xml4pharmaserver.com:8080/UCUMService/rest/ucumtransform/{source_quantity}/from/{source_unit}/to/{target_unit}
or:
http://www.xml4pharmaserver.com:8080/UCUMService/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/UCUMService/rest/ucumtransform/1/from/[in_i]/to/cm
or:
http://www.xml4pharmaserver.com:8080/UCUMService/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/UCUMService/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/UCUMService/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/UCUMService/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/UCUMService/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/UCUMService/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/UCUMService/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/UCUMService/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/UCUMService/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/UCUMService/rest/ucumtransform/1/from/m/(mg2.s2)/to/m.s-2.g-2Annotations
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/UCUMService/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
UCUM for SEND
One of the prejudices (within CDISC) about UCUM is that it would not be usable to units of the preclinical world (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 desperately 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 allow to do any unit conversions. It does e.g. not allow to calculate how many "(L/h)/m2" go into "(L/min)/cm2".
For "PKUNIT", no codelist is necessary: UCUM solves everything!
And 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)Want to know the answer? Then try it yourself! Can you do this using CDISC Controlled Terminology?
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
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
Request string:
http://xml4pharmaserver.com:8080/UCUMService/rest/toBaseUnits/{unit}
For example, if you don't know what the base units of "circular mil" (UCUM notation "[cml_i]"), you submit:
http://xml4pharmaserver.com:8080/UCUMService/rest/toBaseUnits/[cml_i]
Or for "gallon per square foot":
http://xml4pharmaserver.com:8080/UCUMService/rest/toBaseUnits/[gal_us]/[sft_i]
Resulting in:
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.
Another example is breaking down mm[Hg] to the base units:
http://xml4pharmaserver.com:8080/UCUMService/rest/toBaseUnits/mm[Hg]
Which returns (here as XML):
Essentially stating that 1 mm[Hg] = 133322 g.s-2.m-1
Also remark that the entries under "ResultBaseUnitList" can be used for easily treating the result or for chaining
Limitations:
The construct for calling the web service is very similar to that for the simple UCUM Unit Conversion web service, with the extra requirement that a LOINC code must provided at the end.
The HTTP request format is essentially:
http://www.xml4pharmaserver.com:8080/UCUMService/rest/ucumtransform/{source_quantity}/from/{source_unit}/to/{target_unit}/LOINC/{loinc_code}
or:
http://www.xml4pharmaserver.com:8080/UCUMService/rest/ucumtransform/from/{source_unit}/to/{target_unit}/LOINC/{loinc_code}
when the source quantity = 1 (the default)
Examples:
To convert 7.1 mmol/L to mg/dL for LOINC code 14749-6 (Glucose [Moles/volume] in Serum or Plasma), use:
http://xml4pharmaserver.com:8080/UCUMService2/rest/ucumtransform/7.1/from/mmol/L/to/mg/dL/LOINC/14749-6
Resulting in (when XML is requested):
The web service does not only provide the conversion values, but also the molecular weight used. The latter is derived from the LOINC code and retrieved from a database
The other way around: to convert 0.5 mg/dL to umol/dL (a bit of an unconventional unit) for LOINC code 1975-2 (Total Bilirubin [Mass/volume] in Serum or Plasma), use:
http://xml4pharmaserver.com:8080/UCUMService2/rest/ucumtransform/0.5/from/mg/dL/to/umol/dL/LOINC/1975-2
Resulting in:
There may be cases where the molecular weight is not in our database, or that you do not have the LOINC code for the test,
or that you or your application want to provide the molecular weight of the analyte yourself.
In such cases, the construct for calling the web service is:
http://www.xml4pharmaserver.com:8080/UCUMService/rest/ucumtransform/{source_quantity}/from/{source_unit}/to/{target_unit}/MOLWEIGHT/{molecular_weight}
or:
http://www.xml4pharmaserver.com:8080/UCUMService/rest/ucumtransform/from/{source_unit}/to/{target_unit}/MOLWEIGHT/{molecular_weight}
when the source quantity = 1 (the default)
Examples:
You (or your application) wants to provide the molecular weight of glucuse yourself, as 180.156 g/mol, in order to convert 7.1 mmol/L to mg/dL. Then use:
Resulting in:
The other way around: to convert 0.5 mg/dL to umol/mL (a bit of an unconventional unit) for bilirubin with a molecular weight of 584.66 g/mol, use:
Resulting in:
Further details can also be obtained from the document "Instructions for testing the RESTful web service for converting "molar" concentrations to "mass" concentrations and vice versa using UCUM units and LOINC codes"
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: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: April 2020