Guides

Guides

One section per namespace. Each method has a code example and a note on when to reach for it. For exact signatures, options, and return fields, see API-Reference. For the terms used here, see Concepts.

All examples assume a client created as in Getting-Started:

// client.ts
import { createHolonClient } from "@ontomorph/holon-client";

export const holon = createHolonClient({
  apiUrl: "https://holon.ontomorph.com",
  apiKey: process.env.HOLON_API_KEY, // holon_…
});

concepts

Find concepts and walk the hierarchy.

search

// search-concepts.ts
const results = await holon.concepts.search("metformin", {
  domain: "Drug",
  page: 1,
  pageSize: 20,
});
console.log(results.total, "matches");
const top = results.hits[0];

When to use: you have a name or partial term and need the concept behind it. Pass a domain to keep the hits in one category. search returns { hits, total, page, pageSize }.

getById

// concept-by-id.ts
const concept = await holon.concepts.getById("40213251");

When to use: you already hold a conceptId and want the full concept record.

getByCode

// concept-by-code.ts
const concept = await holon.concepts.getByCode("197361", "RxNorm");

When to use: you hold a raw code from a known vocabulary (here RxNorm) and want to resolve it to the HOLON concept.

getAncestors

// ancestors.ts
const ancestors = await holon.concepts.getAncestors(40213251);

When to use: you want the broader concepts above this one, for example to roll a specific drug up to its class.

getDescendants

// descendants.ts
const descendants = await holon.concepts.getDescendants(40213251);

When to use: you want the more specific concepts below this one, for example to expand a class into every member drug.

interactions

Screen drugs for known interactions.

getByDrugId

// drug-interactions.ts
const interactions = await holon.interactions.getByDrugId(11289);

When to use: you want every known interaction recorded for a single drug.

check

// check-pair.ts
const check = await holon.interactions.check(11289, 1191);
if (check.hasInteraction) {
  console.warn(check.interactions.length, "interaction(s) found");
}

When to use: you have two specific drugs and want a pairwise verdict. Returns { hasInteraction, interactions }.

checkList

// check-list.ts
const screen = await holon.interactions.checkList([11289, 1191, 197361]);

When to use: you have a whole medication list and want every interacting pair within it in one call. See the medication-screen scenario in Use-Cases.

mappings

Move a code across vocabularies.

getByConceptId

// mappings-by-concept.ts
const mappings = await holon.mappings.getByConceptId(40213251);

When to use: you hold a concept and want all of its cross-vocabulary mappings at once.

translate

// translate-code.ts
const result = await holon.mappings.translate("197361", "RxNorm", "SNOMED");

When to use: you have a code in one vocabulary and want its equivalent in another. Returns { source, target, mappings }. The target vocabulary is optional. Omit it to get mappings into every available vocabulary:

// translate-all.ts
const all = await holon.mappings.translate("197361", "RxNorm");

referenceRanges

Read normal ranges for lab tests.

getByConceptId

// range-by-concept.ts
const ranges = await holon.referenceRanges.getByConceptId(3004249);

When to use: you hold a HOLON measurement concept and want its reference ranges.

getByLoincCode

// range-by-loinc.ts
const ranges = await holon.referenceRanges.getByLoincCode("2093-3", 45, "male");

When to use: you have a LOINC code and want the range narrowed to a patient's demographic. age and sex are optional. Supply them to narrow the range; omit them for the unadjusted range.

phenotype

Compare sets of phenotype terms.

match

// phenotype-match.ts
const match = await holon.phenotype.match([9826, 4245975], [9826, 31967]);

When to use: you have two sets of phenotype concept ids and want a similarity score, for example to compare two patients or match a presentation to a candidate condition. See the phenotype scenario in Use-Cases.