FHIRfly
Dashboard

UCUM Search API

Search UCUM unit codes for clinical measurements.

Endpoint

GET /v1/ucum/search

Quick Start

Node.js
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for mass units
const results = await client.ucum.search({
  q: "milligram"
});

console.log(`Found ${results.total} units`);
for (const item of results.items) {
  console.log(`${item.code}: ${item.display}`);
}

Parameters

Text Search

Parameter Description Example
q General text search q=milligram

Filters

Parameter Type Description Example
kind string Unit kind prefix, base_unit, unit
property string Physical property mass, volume, pressure
metric boolean Metric units only true
is_common_clinical boolean Commonly used in clinical settings true

Pagination & Response

Parameter Default Max Description
limit 20 100 Results per page
page 1 100 Page number
shape compact — compact, standard, full
sort relevance — relevance, code, display

Example Response

{
  "facets": {
    "kind": {
      "unit": 45,
      "base_unit": 3
    },
    "property": {
      "mass": 12,
      "volume": 8,
      "length": 6
    },
    "metric": {
      "true": 38,
      "false": 10
    }
  },
  "has_more": true,
  "items": [
    {
      "code": "mg",
      "display": "milligram",
      "kind": "unit",
      "property": "mass"
    },
    {
      "code": "mg/dL",
      "display": "milligram per deciliter",
      "kind": "unit",
      "property": "mass concentration"
    }
  ],
  "limit": 2,
  "meta": {
    "legal": {
      "attribution_required": false,
      "citation": "Regenstrief Institute UCUM. Accessed 2026-03-01 via FHIRfly.",
      "license": "public_domain",
      "source_name": "UCUM"
    }
  },
  "page": 1,
  "total": 48,
  "total_capped": false
}

Use Cases

Find Mass Units

Node.js
const results = await client.ucum.search({
  property: "mass",
  is_common_clinical: true
});

Find Metric Volume Units

Node.js
const results = await client.ucum.search({
  property: "volume",
  metric: true
});

Find Common Clinical Units

Node.js
const results = await client.ucum.search({
  is_common_clinical: true,
  sort: "code"
});

Search Pressure Units

Node.js
const results = await client.ucum.search({
  q: "mercury",
  property: "pressure"
});

Facets

UCUM search returns these facets:

Facet Description
kind Distribution by unit kind (prefix, base_unit, unit)
property Distribution by physical property
metric Metric vs non-metric units

Valid Values

Kind Values

  • prefix — Unit prefixes (kilo, milli, micro, etc.)
  • base_unit — Fundamental SI units (meter, gram, second)
  • unit — Derived and named units

Common Property Values

  • mass — Weight/mass measurements
  • volume — Volume measurements
  • length — Length/distance measurements
  • pressure — Pressure measurements
  • time — Time measurements
  • temperature — Temperature measurements
  • concentration — Substance concentration

Required Scope

ucum.search

See Also