Skip to main content

​
Overview

Search for medical concepts using text queries. This endpoint provides fast, relevant results across all supported vocabularies using advanced search algorithms.
This endpoint performs keyword matching - best for exact medical terms like “myocardial infarction” or concept codes like “E11.9”. For natural language queries like “heart attack” or “high blood sugar”, use Semantic Search which uses neural embeddings to understand clinical meaning and returns results ranked by similarity.

​
Query Parameters

​
string
required
Search query text (3-500 characters after surrounding whitespace is removed), or one of the configured whole-query clinical abbreviations: COPD, CHF, MI, T2DM, HTN, and CKD. Other one- and two-character queries are rejected because they are too broad.
Abbreviations are expanded only when they are the complete query. For example, COPD resolves to chronic obstructive pulmonary disease, but COPD exacerbation is searched literally. The deliberately ambiguous bare query MI follows the documented product policy and resolves to myocardial infarction; search a different meaning by its full name.
​
string
Filter search to specific vocabularies (comma-separated)
Examples: SNOMED, SNOMED,ICD10CM, RxNorm,NDC
​
string
Filter by medical domains (comma-separated)
Examples: Condition, Condition,Procedure, Drug,Device
​
string
Filter by concept classes (comma-separated). Class names may contain spaces.
Examples: Disorder, Ingredient, Clinical Finding, AnswerNaming a class that the default ranking policy demotes (see Relevance Scoring below) also turns that demotion off, so concept_class_ids=Answer ranks questionnaire answer-list entries on text relevance alone.
​
integer
default:"1"
Page number (1-based indexing)
​
integer
default:"20"
Number of results per page. Values above 200 are clamped to 200.
​
boolean
default:"false"
Include each result concept’s synonyms array in the response.This does not control whether synonyms are searched — they always are. Use it when you need to see which published term matched, which is often not visible from the concept itself: Bronchial asthma returns 317009 Asthma, whose name contains neither word.
​
boolean
default:"false"
Return only concepts whose concept ID, name, code, or a published synonym equals the query exactly, case-insensitively where applicable.
​
boolean
default:"false"
Include concepts that have been deprecated or replaced in a later vocabulary release. Slower: this cannot use the search index and reads the concept table directly.
​
string
Specific vocabulary release version to query
Example: 2025.1
​
boolean
Whether the search completed.
​
array
Matching concept records.
​
object
Request, release, search, and pagination metadata.
​
number
Normalized effective ranking score in the range 0 to 1. Its non-overlapping bands encode exact identifier intent, clinical utility, and match evidence, so values are non-increasing down the returned ranking. This is not a probability or clinical confidence score. Thresholds calibrated against the earlier additive score must be recalibrated; values should not be compared across queries.
​
'exact' | 'partial'
exact when the query equals the concept ID, concept name, concept code, or a published synonym; otherwise partial for prefix, full-text, and substring matches.

​
Search Features

​
1. Keyword Matching

Matches full words and literal substrings. Basic search does not perform typo correction; use semantic search when keyword overlap is insufficient.

​
2. Synonym & Alias Matching

Every synonym in the OMOP concept_synonym table is indexed alongside the concept name, so a concept is retrievable by any term the vocabulary publishes for it — not only by its own name. This is always on and needs no parameter. In practice this means the phrasings clinicians actually type work: Non-English synonyms are matched the same way where the release contains them — hipertensión arterial esencial returns 320128. This is term matching, not translation: it works for strings that are literally present in concept_synonym, and there is no language detection or query translation. For free-text clinical language in any language, see Multi-lingual Search. A name match outranks a synonym match of comparable quality, so searching Asthma still returns the concept named Asthma first. Pass include_synonyms=true to see the matched concept’s synonym list in the response.
A synonym consisting only of stop words or punctuation cannot be retrieved by keyword search — it produces no searchable terms. This affects a very small number of synonyms (40 of 2.5 million in the 2025.2 release).

​
3. Relevance Scoring

Results are ranked on three explicit dimensions: identifier intent, clinical utility, and lexical evidence. Each dimension occupies a non-overlapping score band. Within an evidence class, a bounded core clinical-domain subtier is applied before full-text rank and trigram similarity. Those raw signals cannot overcome the domain subtier or cross an evidence or clinical-utility boundary. The effective score is normalized and published as match_score (0.0-1.0), so it is non-increasing down the returned ranking. Equal scores may still use vocabulary, name length, and concept_id as deterministic trailing tie-breaks. The value is not a probability. Clients that persisted thresholds against the former additive score distribution must recalibrate them.

​
Default ranking policy

Two concepts can match a query’s text identically and differ enormously in clinical usefulness. LOINC code LA10529-8 is named exactly Diabetes — it is a selectable answer on a questionnaire, not a condition — and it is standard and valid, so nothing downstream rejects it. Ranking it first meant offering a survey-response code as the best match for diabetes. The leading order is:
  1. Exact concept ID or code. Identifier intent wins regardless of Standard status. When a bare code has a recognized ICD10CM, LOINC, or SNOMED shape, the authoritative source is first and its valid Standard Maps to target is second. Supply vocabulary_ids to select a different code system explicitly; use the mapping API when mapping metadata or an explicit source system is required.
  2. Valid Standard clinical concept. This is the default codeable result for OMOP clinical fields.
  3. Valid Classification concept. Useful for grouping but not normally stored in Standard concept-ID fields.
  4. Valid non-standard clinical concept. Still searchable for source-system workflows.
  5. Non-clinical artifact. Questionnaire answers and structural fragments are returned after relevant clinical concepts.
  6. Invalid concept. Returned only when include_invalid=true, and ranked after valid textual matches unless it is the exact requested identifier.
Within each textual utility tier, evidence is ordered as exact primary name, exact published synonym, phrase/prefix, token/full-text, then fuzzy/substring. Possessive eponyms are normalized for primary-name comparison, so Crohn disease matches Crohn's disease. A published synonym with the same English lexeme set also receives exact-synonym evidence regardless of word order and stopwords, so chest x-ray matches the published synonym X-ray of chest. This expansion is limited to multi-lexeme queries, preventing stopword-only additions from changing single-term searches. Within the same evidence class, core clinical domains are preferred before raw full-text and trigram detail. For example, this keeps the generic Condition concept Diabetes mellitus ahead of shorter Observation annotations such as Diabetes type. The non-clinical classes are: The LOINC part classes are fragments of a LOINC code rather than concepts, and carry no standard_concept — they are never codeable. SNOMED Qualifier Value concepts are not demoted even though most of them sit in the Meas Value domain: Positive, Negative and Normal are the concepts you record a measurement value with, and searching for them has to keep working. Core clinical domains (Condition, Drug, Procedure, Measurement, and Device) form that bounded within-evidence subtier. The existing SNOMED/RxNorm/LOINC authority order remains a trailing tie-break only. Vocabulary identity is not used to define whether a concept is Standard. To get the demoted concepts back, name the class or the domain:
A demoted concept is still returned without those filters, with a low match_score, near the end of the result set. Nothing is excluded.

​
4. Multi-vocabulary

Searches across all vocabularies simultaneously.

​
5. Fast Performance

Optimized for sub-second response times.

​
Common Use Cases

​
1. Clinical Coding

Find appropriate codes for clinical documentation.

​
2. Data Standardization

Map free-text clinical notes to standard concepts.

​
3. Quality Assurance

Validate and standardize existing coded data.

​
4. Research Applications

Find concepts for cohort definitions and outcome measures.