The XML4Pharma Application Server

XML4Pharma LOINC Web Services


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.64 (2018-06-15)

NEWS (September 2018): 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 you will need a LOINC username and password.



The following RESTful LOINC web services are currently available by us:


  • Get number of LOINC codes in the database

  • URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCCount

    This service is usually used to test the connection to the service


  • Get LOINC core properties from LOINC code
  • When a LOINC code (e.g. "1751-7") is submitted the most important properties are returned. These are:


    URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCCoreProperties/{LOINC-Code}
    Example: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCCoreProperties/1751-7
    Remark that for each of the parts of the properties, you can retrieve the full name using the 'Get explanation for LOINC part' service (by chaining)


  • Get LOINC Name from LOINC code
  • 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


  • Get LOINC long name from LOINC code
  • 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


  • Search LOINC based on similarity with LOINC long name
  • 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.
    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"


  • Get example UCUM units for LOINC code
  • 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


  • Get molar mass for LOINC code
  • When a LOINC code (e.g. "2339-0" for "Glucose:MCnc:Pt:Bld:Qn") is submitted the molar mass '180.2' of the component (Glucose) is returned. This can enormously help converting values between two (otherwise equal) tests where one test reports the resuls using moles (SCnc: substance concentration) and the other using mass (MCnc) or vice versa.
    For example, LOINC test "15074-8" ("Glucose:SCnc:Pt:Bld:Qn") only differs with LOINC code "2339-0" in that the results are expressed as molar concentration instead of mass concentration.
    URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCMolarMass/{LOINC-Code}
    Example: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCMolarMass/15074-8

    Remark that this service uses an older version of the LOINC database, as molecular masses are (unfortunately) not present anymore in version 2.58.


  • Get molar mass for LOINC component
  • Similar as for the previous service, when a LOINC component (e.g. "Cyclohexane") is submitted the molar mass '84.161' of the component is returned. This can enormously help converting values between two (otherwise equal) tests where one test reports the resuls using moles (SCnc: substance concentration) and the other using mass (MCnc).
    The component is searched for in the LOINC database in a case-insensitive way.
    URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCMolarMassForComponent/{component}
    Example: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCMolarMassForComponent/cyclohexane

    Remark that this service uses an older version of the LOINC database, as molecular masses are (unfortunately) not present anymore in version 2.58.


  • Search for LOINC code for a specific compound/component
  • 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):


  • Search for LOINC code for a specific compound/component in a specific system/specimen type
  • 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"

    URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCSearch/component/{component}/system/{system}

    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):


  • Get similar/related tests for given test by LOINC code
  • 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:

    URL: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCSimilarTest/{LOINC-Code}
    Example: http://www.xml4pharmaserver.com:8080/LOINCService/rest/LOINCSimilarTest/1751-7
    providing all tests that are similar/related to the test "Albumin [Mass/volume] in Serum or Plasma" (LOINC code 1751-7).


    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"


  • Get explanation for LOINC part
  • 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.


    Most of these services have been implemented in the Smart Dataset-XML Viewer, 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 2017