Search by meaning

Code sets use their own wording. Someone looking for "diabetes with kidney disease" means E11.22 Type 2 diabetes mellitus with diabetic chronic kidney disease, and "kidney damage from high blood pressure" means the I12 hypertensive chronic kidney disease codes, although the words differ. GET /v1/search finds them: it ranks codes and drugs by how close they are in meaning to your query and by the query words their text contains.

Search by meaning is part of the Builder plan and up. On Free it answers 403 plan-upgrade-required (see Plans); the wording-based searches (/v1/codes/{system}?q=, /v1/drugs/search) are on every plan.

curl "https://api.healthcare.dev/v1/search?q=diabetes%20with%20kidney%20disease&system=icd10cm" \
  -H "Authorization: Bearer $HDEV_API_KEY"

const { data } = await hdev.search.meaning({
  q: "diabetes with kidney disease",
  system: "icd10cm",
});

{
  "data": [
    {
      "system": "icd10cm",
      "code": "E11.22",
      "display": "Type 2 diabetes mellitus with diabetic chronic kidney disease",
      "status": "active",
      "href": "/v1/codes/icd10cm/E11.22",
      "match_score": 0.8,
      "reason": "matches \"diabetes\", \"kidney\", \"disease\" in the description",
      "did_you_mean": [
        {
          "system": "icd10cm",
          "code": "E10.22",
          "display": "Type 1 diabetes mellitus with diabetic chronic kidney disease"
        }
      ],
      "record": { "code": "E11.22", "billable": true, "...": "..." }
    }
  ],
  "meta": { "source": "cms-icd10", "data_version": "fy2027", "...": "..." },
  "links": { "self": "/v1/search?q=...", "next": "/v1/search?q=...&cursor=..." }
}

What it searchesCopy Anchor Link

ICD-10-CM, ICD-10-PCS, HCPCS Level II, RxNorm concepts and FDA NDC products, ranked together. Pass system to search some of them: one (system=icd10cm) or several, comma-separated (system=rxnorm,ndc). Retired codes are not searched by meaning; look them up by code.

meta describes the datasets searched. When there are several, meta.sources lists each one's version, source and license terms.

match_scoreCopy Anchor Link

A number from 0 to 1, best first:

Closeness in meaning can raise a result's score above its wording alone, never lower it. Scores compare results within one search; don't compare them across different queries.

reasonCopy Anchor Link

A few words on why each result matched:

• exact code match, code starts with "E11.2"
• matches "kidney", "disease" in the description (drugs: "in the name")
• close in meaning to "high blood pressure": the part of your query the text doesn't say in so many words, but means
• loosely related; check it

did_you_meanCopy Anchor Link

When the top results are close in score but come from different code families (an ICD-10 category such as E10 versus E11, a HCPCS section, or drugs versus codes), the first result carries did_you_mean: the best match of each other family. "Diabetes with kidney disease" doesn't say type 1 or type 2, so E11.22 comes with E10.22. Ask your user, or add the missing detail to the query, rather than picking one.

Paging, views and fieldsCopy Anchor Link

Results page like every other search (limit, default 25, max 100; follow links.next), up to the best 100 matches per system. ?view=compact returns system, code, display, match_score, reason and did_you_mean; ?fields= picks fields; the default includes the full record. Each search is billed as one call.

How it worksCopy Anchor Link

Every record's description is turned into a numeric fingerprint of its meaning when we load a release, and stored with that release. Your query gets the same treatment on our servers when you search, and is compared with the stored fingerprints, then with the words of the text. Nothing is sent to a third party, results are repeatable for the same query and data version, and a new release is searchable by meaning as soon as it's published.

In MCPCopy Anchor Link

The search_by_meaning tool calls this endpoint with view=compact and returns one line per result with its score and reason, plus the did_you_mean alternatives. Use search_codes or search_drugs when you know the official wording; see Tools.