FHIRfly
Dashboard

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

Request
Node.js
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);
Response
JSON
{
  "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

Request
Node.js
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);
Response
JSON
{
  "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

Request
Node.js
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);
Response
JSON
{
  "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