|
|
We have developed a good number of RESTful Web Services for use with LOINC, the universal code system for medical lab tests, measurements, and observations.
Latest LOINC version implemented: 2.78 (2024-08-06)
Please also have a look at the new LOINC RESTful web services provided by the "LOINC FHIR Terminology Server".
These have a good overlap with our RESTful web services, but are maintained by the LOINC organization itself.
When trying them out, I first encountered some problems with the services certificate, but also soon found a solution. Some source code for Java and a solution for the problems with the certificate
can be found on the website's forum.
IMPORTANT: For this RESTful web service at the LOINC FHIR Terminology Server you will need a LOINC username and password.
The following RESTful LOINC web services are currently available by us:
This service is usually used to test the connection to the service
When a LOINC code (e.g. "1751-7") is submitted the most important properties are returned. These are:
When a LOINC code (e.g. "1751-7") is submitted the LOINC name is returned. In the example case the response is: "Albumin:MCnc:Pt:Ser/Plas:Qn" meaning:
Albumin mass concentration as a point in time in serum/plasma, quantitative.
URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCName/{LOINC-Code}
Example: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCName/1751-7
When a LOINC code (e.g. "1751-7") is submitted the LOINC Long Name is returned. In the example case the response is: "Albumin [Mass/volume] in Serum or Plasma"
URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCLongName/{LOINC-Code}
Example: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCLongName/1751-7
This service allows you to get suggested LOINC codes (and their properties) by submitting a search string. This search string is compared
with the LOINC long (common) name, and the hits are ordered by similarity (based on the Levenshtein algorithm). Optionally, one can add a second parameter indicating
the maximum number of LOINC objects to be returned. Limiting the number of answers will also usually reduce the response times.
The maximum number of answers is always limited to 200. So, it does not make sense to set a higher number than 200.
URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCSuggestTests/{searchTerm}
URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCSuggestTests/{searchTerm}/{maxAnswers}
Examples:
This web service can easily be used in software that needs to suggest suitable LOINC codes, e.g. for mapping with local codes.
Limitations: at this moment the order in which the words are present in the search string matters: you will obtain different answers (and in different order)
when searching for "albumin serum"
than for searching "serum allbumin".
So if you want to search for "Albumin in serum or plasma", do not use the search term "serum albumin"
When a LOINC code (e.g. "1751-7") is submitted the example UCUM unit is returned. This corresponds to the unit in which the results are usually reported for this lab test.
In the example case the response is: "g/dL"
URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCExampleUCUMUnits/{LOINC-Code}
Example: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCExampleUCUMUnits/1751-7
This service allows your application to search for all LOINC codes for a given compound/component
URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCSearch/component/{component}When searching for the LOINC codes for a compound/component, you can use a "wildcard" ('*') at the beginning or end of the string. For example:
Remark that the search is done "case-insensitive".
Limitations:
Example response (XML):
This service allows your application to search for all LOINC codes for a given compound/component in a specific system/specimen, where the system can be e.g.
"Ser/Plas" (Serum or plasma), "Urine" or "Bld" (blood) or "Periton fld" (peritonal fluid).
It can however also be the whole patient, defined as "^Patient"
When searching for the LOINC codes for a compound/component and for the system/specimen, you can use a "wildcard" ('*') at the beginning or end of the string. For example:
Remark that the search is done "case-insensitive".
Limitations:
Example response (XML):
This service provides a detailed list of tests which are similar (or related) to a given test as provided by the LOINC code.
The list is sorted by:
Depending whether your (applications) HTTP request asks for XML, JSON or text, you will get the information back as XML, JSON or just a single string.
The XML returned by the service "get LOINC name from LOINC code" has the following structure (example):
and for the service "get LOINC long name from LOINC code:
For the service "Get similar/related tests for given test by LOINC code", here is an example of the output:
As one can see, the first test in the list (2862-1) only differs by the method, which is "by electrophoresis"
LOINC is essentially a 5-dimensional system, sometimes (when absolutely necessary) a 6th dimension is added. These dimensions, also named parts are:
There are however also other (non-identifying) parts, such as "CLASS", "TIME MODIFIER", ...
It is not always easy to understand what a part name means. For example, do you know what "Ser/Plas/BldV" for the part "system" means? Well it means "Serum or Plasma + Blood venous".
This RESTful web service allows you (or better: your application) to find out.
URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCPartExplanation/{parttype}/{partname}
Where "parttype" is one of the 6 dimension names (component, property, time, system, scale, method) extended with (less used):
"challenge", "divisors", "class", "super system", "adjustment", "quotient", "time modifiers", "count" and a number of others used in radiology.
Example: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCPartExplanation/property/MCnc
returning "Mass Concentration".
Example: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCPartExplanation/method/BCG
returning "Bromocresol green (BCG) dye binding".
The partname can itself contain slashes, that is no problem.
Example: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCPartExplanation/system/Ser/Plas/BldV
returns "Serum or Plasma + Blood venous"
Example: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCPartExplanation/class/chem
returns "Chemistry non challenge tests"
Example: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCPartExplanation/class/sero
returns "Serology tests (non micro)"
Remark that the values for the parameters {parttype} and {partname} are case-INsensitive. So you can e.g. use as well "/CLASS/CHEM" as well as "/class/chem".
This may be of interest to do chaining, e.g. first ask the core properties for a LOINC code, and then use the result to ask for the explanation of what the value of the "class" means.
This RESTful web service can not only very well be used for systems that need to provide human-understandable information about the LOINC parts,
but e.g. also for mapping to SDTM, where variables like LBMETHOD, LBSPEC, LBCAT need to be derived from the LOINC code in LBLOINC.
(Remark that the FDA requirement to provide LBTESTCD, LBTEST, ... etc when a value for LBLOINC is already provided, is essentially nonsense.
A LOINC panel groups tests that belong together. Panels can be not only laboratory panels, such as for LOINC code 78699-6
(Liver fibrosis score panel - Serum or Plasma Calculated by FibroMeter), but also e.g. vital signs panels, such as for LOINC code 34566-0
(Vital Signs panel). Essentially, LOINC Panels are nothing else than a type of CDISC Biomedical Concepts,
which can also be represented by a CDISC ODM Form.
Therefore, we developed a RESTful web service that generates a full CDISC ODM 1.3.1 metadata file containing a form with all the items from the LOINC panel,
including units of measurement, and codelists.
URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCPanelToODMForm/{loinccode}
Where "loinccode" is the LOINC code of a LOINC panel
Example: http://xml4pharmaserver.com:8080/LOINCService/rest/LOINCPanelToODMForm/95826-4
returns an ODM document with a form representing the LOINC panel 95826-4:
"SARS-CoV-2 (COVID-19) RNA panel - Saliva (oral fluid) by NAA with probe detection".
The ODM form can then be directly embedded into a study design. It also contains instructions for SDTM mapping in the case it is a lab form (LBLOINC)
A snippet of the ODM form is shown below:
In case the LOINC code does not represent a LOINC panel, a response with text is "This LOINC code does not represent a panel or questionnaire" is returned.
When a LOINC code is submitted that has as "property" the value "MCnc" (mass concentration), the service will attempt to find a corresponding LOINC code which has the "property" with the value "SCnc" (substance concentration) with all details. If no corresponding LOINC code is found, or the LOINC code is invalid, the service returns a simple "No LOINC code found".
URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCMassToSubstance/{loinccode}
Example: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCMassToSubstance/1751-7
Submits the LOINC code 1751-7 (Albumin [Mass/volume] in Serum or Plasma) and returns the LOINC code 54347-0 (Albumin [Moles/volume] in Serum or Plasma) with all the details.
This service is especially important for finding the "standardized units" when doing "conventional units" to "SI units" conversions in CDISC-SDTM sumissions to the FDA. Such unit conversions can then be automated in our SDTM-ETL mapping software.
When a LOINC code is submitted that has as "property" the value "SCnc" (substance concentration), the service will attempt to find a corresponding LOINC code which has the "property" with the value "MCnc" (mass concentration) with all details. If no corresponding LOINC code is found, or the LOINC code is invalid, the service returns a simple "No LOINC code found".
URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCSubstanceToMass/{loinccode}
Example: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCSubstanceToMass/54347-0
Submits the LOINC code 54347-0 (Albumin [Moles/volume] in Serum or Plasma) and returns the LOINC code 1751-7 (Albumin [Mass/volume] in Serum or Plasma) with all the details.
This service is especially important for finding the "standardized units" when doing "SI units" to "conventional units" conversions in CDISC-SDTM sumissions to the FDA. Such unit conversions can then be automated in our SDTM-ETL mapping software.
Most of these services have been implemented in the Smart Dataset-XML Viewer, and in our
SDTM-ETL mapping software but you can of course use them
in any software application that you want using RESTful web services.
Also see our blogs at blogspot
If you have any suggestions for other web services which have to do with LOINC, UCUM, CDISC and CDISC Controlled Terminology, please let us know.
Courtesy of XML4Pharma - last update: June 2021