UCUM (Units of Measure) API
Look up UCUM unit codes for standardized clinical measurements.
Overview
UCUM (Unified Code for Units of Measure) is maintained by the Regenstrief Institute and provides a code system for unambiguous representation of measurement units. FHIRfly provides fast lookups, validation, and conversion against the UCUM specification.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /v1/ucum/:code | Single UCUM lookup |
| POST | /v1/ucum/_batch | Batch lookup (up to 100) |
| GET | /v1/ucum/shapes | List available response shapes |
| GET | /v1/ucum/validate/:expression | Validate a UCUM expression |
| GET | /v1/ucum/convert | Convert between UCUM units |
Single Lookup
Look up milligram unit
const response = await fetch(
"https://api.fhirfly.io/v1/ucum/mg",
{
method: "GET",
headers: {
"x-api-key": "YOUR_API_KEY",
}
}
);
const data = await response.json();
console.log(data);{
"data": {
"code": "mg",
"display": "milligram",
"kind": "unit",
"property": "mass",
"metric": true,
"is_special": false,
"print_symbol": "mg",
"is_common_clinical": true,
"fhir_coding": {
"code": "mg",
"display": "milligram",
"system": "http://unitsofmeasure.org"
}
},
"meta": {
"legal": {
"attribution_required": false,
"citation": "Regenstrief Institute UCUM. Accessed 2026-03-01 via FHIRfly.",
"license": "public_domain",
"source_name": "UCUM"
}
}
}Common UCUM Codes
| Code | Unit | Property |
|---|---|---|
mg | milligram | mass |
kg | kilogram | mass |
mL | milliliter | volume |
mmHg | millimeter of mercury | pressure |
[lb_av] | pound (avoirdupois) | mass |
% | percent | fraction |
mmol/L | millimole per liter | concentration |
g/dL | gram per deciliter | mass concentration |
Batch Lookup
Look up multiple UCUM codes in a single request (up to 100):
Look up multiple units
const response = await fetch(
"https://api.fhirfly.io/v1/ucum/_batch",
{
method: "POST",
headers: {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
"codes": [
"mg",
"kg",
"mL"
]
})
}
);
const data = await response.json();
console.log(data);{
"count": 3,
"results": [
{
"input": "mg",
"code": "mg",
"status": "ok",
"data": {
"display": "milligram",
"kind": "unit",
"property": "mass"
}
},
{
"input": "kg",
"code": "kg",
"status": "ok",
"data": {
"display": "kilogram",
"kind": "unit",
"property": "mass"
}
},
{
"input": "mL",
"code": "mL",
"status": "ok",
"data": {
"display": "milliliter",
"kind": "unit",
"property": "volume"
}
}
],
"meta": {
"legal": {
"license": "public_domain"
}
}
}Batch with shape=full
When using shape=full on batch requests, the response includes meta.source with provenance information:
POST /v1/ucum/_batch?shape=full
{
"count": 3,
"results": [
{
"input": "mg",
"code": "mg",
"status": "ok",
"data": { "display": "milligram", "kind": "unit", "property": "mass" }
}
],
"meta": {
"source": {
"name": "UCUM",
"url": "https://ucum.org",
"version": "2.1",
"fhirfly_updated_at": "2026-03-01T03:00:00Z"
},
"legal": {
"license": "public_domain",
"attribution_required": false
}
}
}
Validate Expression
Check whether a UCUM expression is syntactically valid:
Validate a UCUM expression
const response = await fetch(
"https://api.fhirfly.io/v1/ucum/validate/mg%2FdL",
{
method: "GET",
headers: {
"x-api-key": "YOUR_API_KEY",
}
}
);
const data = await response.json();
console.log(data);{
"data": {
"expression": "mg/dL",
"valid": true,
"normalized": "mg/dL"
},
"meta": {
"legal": {
"license": "public_domain",
"source_name": "UCUM"
}
}
}This is useful for validating unit strings received from EHR systems or user input before using them in calculations.
Convert Units
Convert a value from one UCUM unit to another:
GET /v1/ucum/convert?from=mg&to=g&value=1000
{
"data": {
"from": "mg",
"to": "g",
"input_value": 1000,
"result_value": 1,
"valid": true
},
"meta": {
"legal": {
"license": "public_domain",
"source_name": "UCUM"
}
}
}
Conversion is only supported between commensurable units (same dimension). Attempting to convert between incompatible units (e.g., mg to mL) returns an error.
Response Shapes
Control the level of detail in responses with the shape query parameter:
| Shape | Description |
|---|---|
compact | Code, display, kind, property |
standard | + metric, is_special, print_symbol, is_common_clinical, fhir_coding |
full | + class, value, ingest metadata |
# Minimal data
GET /v1/ucum/mg?shape=compact
# Standard data (default)
GET /v1/ucum/mg?shape=standard
# Full data with provenance
GET /v1/ucum/mg?shape=full
See Response Shapes for field details.
Required Scopes
ucum.read- Single and batch lookups, validation, and conversion