LOINC-API

Introduction

Shaip introduces the "LOINC API", a tool crafted to convert unstructured EHR data into standardized LOINC codes, essential for representing diverse medical observations and ensuring efficient data exchange. Using state-of-the-art NLP, the API offers pinpoint LOINC code recommendations, enhancing the accuracy of medical data interpretation. Key features include precise NLP-driven code suggestions and effortless REST API integration for broad healthcare system compatibility. Shaip's LOINC API equips healthcare professionals with an automated solution for LOINC code assignments, fostering enhanced clinical insights and promoting consistent medical practices in today's dynamic healthcare environment.

By harnessing Shaip's LOINC API, healthcare professionals and researchers gain access to a powerful tool that automates and enhances the accuracy of LOINC code assignment. Embrace our advanced API to unlock new dimensions of clinical insights, streamline data processing, and promote standardized medical practices in the ever-evolving landscape of healthcare.

Authentication

The LOINC API also follows a secure authentication mechanism using API keys to ensure safe and authorized access to its powerful functionality. To make requests to the LOINC API, developers must include their unique API key in the request headers. The x-api-key header should contain the provided API key, which will be given upon registration and subscription to the API service.

To maintain security, it is essential to treat the API key as confidential information and avoid sharing it in public spaces like client-side code, version control repositories, or public forums. The API key serves as a crucial access credential, granting specific privileges to interact with the LOINC API.

To authenticate API requests, include the x-api-key header in each POST request. This header allows the server to verify your credentials and provide access to the LOINC service.

API Endpoint:

URL: {LOINC_API_ENDPOINT}
Method: POST
Headers:
Content-Type: "application/json"
x-api-key:{YOUR_API_KEY}

Ensure that you include the appropriate authentication details and headers with each API call to enjoy uninterrupted access to the LOINC API's powerful functionality. Our secure authentication process is thoughtfully designed to safeguard sensitive medical data and ensure that only authorized users can leverage this valuable service.

Replace {YOUR_API_KEY} with your unique API key provided upon registration and subscription to the LOINC API service. Also, replace {YOUR_UNSTRUCTURED_TEXT} with the actual unstructured medical text, such as Electronic Health Record (EHR) data or any relevant medical text that you want to convert into LOINC codes. Ensure that the content is properly formatted and adheres to the API's guidelines to receive precise LOINC code recommendations.

CURL

1curl -X POST "https://haiapi.shaip.com/loinc_output" 
2
3     -H "Content-Type: application/json" 
4
5     -H "x-api-key: {YOUR_API_KEY}" 
6
7     -d '{
8            "content": "{YOUR_UNSTRUCTURED_TEXT}"
9         }'
10

API Request

Request Parameter

To use Shaip's LOINC Code Recommendation API, you need to make a well-organized request with a key piece of information:

Content (String, Required): This field should contain the unstructured medical text, like Electronic Health Record (EHR) data or relevant medical information, in a simple text format. It's crucial to format the content correctly following the API guidelines to get accurate LOINC code suggestions.

You can make the request using the CURL command provided in the code section

CURL

JAVA

Python

NodeJS

Ruby

PHP

.NET(C#)

1curl -X POST "https://haiapi.shaip.com/loinc_output" 
2
3     -H "Content-Type: application/json" 
4
5     -H "x-api-key: wVxnqO9v773XDTxAnTadUa94v6eN1L4MWJDygVs1" 
6
7     -d '{
8            "content": "LAB RESULTS:
91. CBC:
10- Hemoglobin: 12.5 g/dL
11- White Blood Cells: 7.5 K/uL
12- Platelets: 200 K/uL
13
142. CMP:
15- Sodium: 140 mmol/L
16- Potassium: 4.0 mmol/L
17- Creatinine: 1.2 mg/dL
18- Glucose: 95 mg/dL"
19         }'
20
21

CURL

JAVA

Python

NodeJS

Ruby

PHP

.NET(C#)

1curl -X POST "https://haiapi.shaip.com/loinc_output" 
2
3     -H "Content-Type: application/json" 
4
5     -H "x-api-key: wVxnqO9v773XDTxAnTadUa94v6eN1L4MWJDygVs1" 
6
7     -d '{
8            "content": "LAB RESULTS:
91. CBC:
10- Hemoglobin: 12.5 g/dL
11- White Blood Cells: 7.5 K/uL
12- Platelets: 200 K/uL
13
142. CMP:
15- Sodium: 140 mmol/L
16- Potassium: 4.0 mmol/L
17- Creatinine: 1.2 mg/dL
18- Glucose: 95 mg/dL"
19         }'
20
21

API Response

Response Parameter

The LOINC Code Recommendation API provides a structured and comprehensive response to aid in the efficient integration of LOINC codes into healthcare systems. The response consists of three main tables - Code, Evidence, and TextSpan, each containing essential details as follows:

Code

codingSystem (Enum, Required): This field indicates the coding system from which the LOINC code is derived. For this API, the value will always be "LOINC."

value (String, Required): This field contains the actual value of the LOINC code, such as "24356-8" representing a specific medical concept.

evidence (List<Evidence>, Optional): This field contains a list of evidence (if available) that supports the recommended LOINC code. Each element in the list corresponds to a piece of evidence contributing to the code recommendation.

textSpan (TextSpan, Required): This field represents the content of the entity that serves as evidence for the recommended LOINC code. It refers to the specific portion of the medical document where the evidence is extracted.

beginOffset (Integer, Required): This field contains the calculated beginning offset of the textSpan content within the original medical document. The offset refers to the character position where the textSpan starts.

text (String, Required): This field contains the actual content of the textSpan. It represents the extracted text that serves as evidence for the LOINC code recommendation

certainty (Enum, Required): This field contains the certainty value of the detected entity from the following list: [List of Certainty Values]. The certainty value indicates the level of confidence in the entity's presence or accuracy.

section (TextSpan, Required): This field contains the text span describing the section from where the evidence has been detected. It helps identify the context of the evidence within the medical document.

Response Parameter Values

Coding System Values

LOINC : LOINC (Logical Observation Identifiers Names and Codes) is a standardized coding system used for identifying and exchanging medical laboratory test results and clinical observations. It enables consistent communication of laboratory data across healthcare settings.

Certainty Values

POSITIVE - A positive certainty indicates the entities are confirmed and present positively in the patient’s record. e.g. The patient has hypertension and is on diuretics. In this example "hypertension" is positive and the patient is taking "diuretics" which also indicates that it is positive.

POSSIBLE_POSITIVE - A possible positive certainty indicates the entities are present but are not accurate and valid. e.g. The wound of the patient appears to be granulating. In this example the word "appears to be" is possibly positive as it is not confirmed evidence.

NEGATIVE - A negative certainty indicates the entities are not present. e.g. The patient does not have vomiting and nausea. In this example evidence "vomiting" and "nausea" are not present in the patient.

POSSIBLE_NEGATIVE - A possible negative certainty indicates the entities are not totally absent but are present insignificantly. e.g. The patient’s wound abscess was resolving. In this example "resolving" is a possible negative word which means wound abscess is not treated completely and hence cannot be marked as negative.

UNCERTAIN - Uncertainty indicates the state of doubt to determine. It is the situation in which something is not known or not certain. e.g. The doctor was unable to determine the cause of the swelling. In this example "unable to determine" indicates uncertainty.

CONDITIONAL - Conditional indicates hypothetical situations and their consequences. e.g. The doctor said that the patient should also come back if he develops pain, fever, nausea, vomiting, or any other concerning symptoms. In this example "if he develops" is conditional.

FAMILY_HISTORY - Family history provides the information of all the diseases and illnesses within the family of the patient. e.g. The patient has a family history of hypertension. This example shows that "hypertension" was present in his family.

FUTURISTIC - It indicates the events that will happen after the present time. E.g. The doctor said that he will check the wound after 5 days. In this example "will check" indicates the future status.

JSON

1{
2  "icd10cmcodes":  [],
3  "requestId":  267
4}

Error

When interacting with the Shaip API, you may encounter specific error codes, along with standard HTTP response statuses and corresponding error messages in the response body. Below is a table summarizing the possible error codes, along with their respective HTTP status and updated response body:

Response Code	HTTP Status	Response Body
400	Bad Request	{ "error": "The request was unacceptable, often due to missing a required parameter." }
401	Unauthorized	{ "error": "No valid API key provided." }
402	Token Expired	{ "error": "Token expired. Please contact administrator" }
403	Forbidden	{ "error": "The API key doesn't have permissions to perform the request." }
429	Trial Quota Excceded	{ "error": "Trial quota for API calls exceeded. Please upgrade your plan or try again later." }
500	Internal Server Error	{ "error": "Something went wrong on the server's end. Please try again later." }

400

401

402

403

429

500

1{
2	"error": "The request was unacceptable, often due to missing a required parameter."
3}