LOINC API Documentation

{beta}


Cheat sheet


Endpoints

Specific LOINC code

Call

Use the URL format api.aqua.io/codes/beta/loinc/CODE_NAME.json via an HTTP GET request.

Read more about LOINC codes and their elements in the LOINC User's Guide.

Response

Field
Explanation
Example Value
name
The LOINC code.
883-9
long_common_name
The common, semantic name of the code describes.
ABO group [Type] in Blood
category
The appropriate code category.
BLDBK
explanation
Explanation of code and how to use it (if applicable).
Absolute CD4 T-cell counts are required to monitor immune status of HIV patients... [LOINC code 65758-5]
test_name
The full, multi-part name of the LOINC test.
ABO group:Type:Pt:Bld:Nom
test_name_breakdown
Breakdown of the individual parts of the full LOINC test name.
{"full_analyte": "ABO group", "analyte_subpart_1": "ABO group", "analyte_subpart_2": "", "analyte_subpart_3": "", "analyte_subpart_4": "", "property": "Type", "time_aspect": "Pt", "system": "Bld", "scale": "Nom", "scale_explanation": "Nominal", "scale_comments": "Nominal or categorical responses that do not have a natural ordering. (e.g., names of bacteria, reported as answers, categories of appearance that do not have a natural ordering, such as, yellow, clear, bloody. (Previously named QL) (p. 25, 2012 LOINC Users Guide)", "method": ""}
status
If code is active or not. If not active (i.e., "status":{"active":false,...), an explanation is typically provided.
{"active": false, "explanation": "DEPRECATED (Erroneous): Term erroneous. Mapped to 71693-6."} [LOINC code 70032-8]
short_name
A shorthand name for the test, if available.
ABO Group Bld
consumer_name
The retail/consumer name of the test, if available.
Gabapentin serum/plasma [LOINC code 70032-8]
rank
Rankings of how frequently the codes are used, if available.
{"common_test_rank": "218", "common_order_rank": "177", "common_si_test_rank": "218"}
related_terms
An array of related names/terms for this code.
[{"related_term":{"name":"Point in time"}},{"related_term":{"name":"Random"}},{"related_term":{"name":"Quantitative"}},{"related_term":{"name":"QNT"}},{"related_term":{"name":"Quant"}},{"related_term":{"name":"Quan"}},{"related_term":{"name":"WB"}},{"related_term":{"name":"Blood"}},{"related_term":{"name":"Whole blood"}},...
Full output for LOINC code 883-9

Good to know

  • A malformed code request will return a 404 Status Error and, in many cases, an array of possible matches. For example api.aqua.io/codes/beta/loinc/7187.json returns

    {"possible_matches": [{"name": "718-7", "long_common_name": "Hemoglobin [Mass/volume] in Blood", "category": "HEM/BC", "test_name": "Hemoglobin:MCnc:Pt:Bld:Qn", "explanation": "", "url": "https://api.aqua.io/codes/loinc/718-7.json"}, {"name": "7183-7", "long_common_name": "Cashew Nut IgG Ab [Units/volume] in Serum", "category": "ALLERGY", "test_name": "Anacardium occidentale Ab.IgG:ACnc:Pt:Ser:Qn", "explanation": "", "url": "https://api.aqua.io/codes/loinc/7183-7.json"}, ...]}

    This can be useful for returning a 'did you mean...?' list of options to a user, if an inputted code contains a typo.

List of common codes

Call

Use the URL format api.aqua.io/codes/beta/loinc.json via an HTTP GET request.

Response

Returns a JSON array of responses for the most commonly used codes, each containing the following fields:

Field
Explanation
Example Value
name
The LOINC code.
100-8
long_common_name
The common, semantic name of the code describes.
Cefoperazone [Susceptibility] by Minimum inhibitory concentration (MIC)
url
API URL for the code.
https://api.aqua.io/codes/loinc/100-8.json
Output for most common LOINC codes.

Good to know

  • Since there are over 70,000 LOINC codes, this index action currently only returns the most commonly used codes.

    The roughly 2200 codes returned by this action are drawn from LOINC's common order, common test, and common SI test rankings, and are likely to change with time.
  • Results returned are ordered by LOINC code ('name'), not by popularity.

Search

Call

Use the URL format GET .../loinc.json?utf8=✓&q%5BSEARCH_PARAMETERS%5D=QUERY via an HTTP GET request.

Response

Returns a JSON array of matching results, each containing the following fields:

Field
Explanation
Example Value
name
The LOINC code.
100-8
long_common_name
The common, semantic name of the code describes.
Cefoperazone [Susceptibility] by Minimum inhibitory concentration (MIC)
url
API URL for the code.
https://api.aqua.io/codes/loinc/100-8.json

Query Parameters

Currently, a search may only query a code's 'name', 'long_common_name', 'category', 'explanation', 'short_name' or a combination of these fields ('name_or_long_common_name_or_short_name'). Each field may be queried using any of the following suffixes:

Suffix
Explanation
Example Implementation
X_cont=Y
Field X contains Y
...%5Blong_common_name_cont%5D=HIV...
X_start=Y
Field X starts with Y
...%5Bname_start%5D=66...
X_end=Y
Field X ends with Y
...%5Bname_end%5D=06...

Good to know

  • Results returned are ordered by LOINC code ('name').