Semantic Search

curl -X GET "https://api.omophub.com/v1/search/semantic?query=heart%20attack&page_size=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "query": "heart attack",
    "results": [
      {
        "concept_id": 4329847,
        "concept_name": "Myocardial infarction",
        "domain_id": "Condition",
        "vocabulary_id": "SNOMED",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "concept_code": "22298006",
        "similarity_score": 0.92,
        "matched_text": "Myocardial infarction"
      }
    ],
    "total_results": 45,
    "retrieval_truncated": false,
    "totals_are_lower_bound": false,
    "latency_ms": 28
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 45,
      "total_pages": 3,
      "has_next": true,
      "has_previous": false
    },
    "request_id": "req_sem_abc123"
  }
}

curl -X GET "https://api.omophub.com/v1/search/semantic?query=heart%20attack&page_size=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "query": "heart attack",
    "results": [
      {
        "concept_id": 4329847,
        "concept_name": "Myocardial infarction",
        "domain_id": "Condition",
        "vocabulary_id": "SNOMED",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "concept_code": "22298006",
        "similarity_score": 0.92,
        "matched_text": "Myocardial infarction"
      }
    ],
    "total_results": 45,
    "retrieval_truncated": false,
    "totals_are_lower_bound": false,
    "latency_ms": 28
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 45,
      "total_pages": 3,
      "has_next": true,
      "has_previous": false
    },
    "request_id": "req_sem_abc123"
  }
}

Overview

Find OMOP concepts related in meaning to an English-language query, even when the wording differs from the concept name. Results are suggestions for review, not automatic clinical coding decisions. Example queries:

“heart attack” finds “Myocardial infarction”
“sugar diabetes” finds “Type 2 diabetes mellitus”
“high blood pressure” finds “Essential hypertension”
“belly pain” finds “Abdominal pain”

When to Use Semantic Search

Need	Recommended endpoint
Related concepts from an English phrase	Semantic search
Exact name, synonym, or code lookup	Basic search
Convert a source concept to OMOP Standard	Concept mappings

Query Parameters

string

required

English natural-language search query. After trimming, queries must contain 3-500 characters. MI is also accepted as a case-insensitive abbreviation. Other 1-2 character queries are rejected.

integer

default:"1"

Page number (1-based)

integer

default:"20"

Results per page (1-100)

number

default:"0.5"

Minimum similarity score (0.0-1.0). Higher values return fewer, closer matches. This score is not a probability or clinical confidence value.

string

Filter to specific vocabularies (comma-separated)
Examples: SNOMED, SNOMED,ICD10CM, SNOMED,ICD10CM,RxNorm

string

Filter to specific domains (comma-separated)
Examples: Condition, Drug, Condition,Drug,Procedure

string

Filter by standard concept status
Values: S (Standard), C (Classification), N (Non-standard; stored as null in OMOP)

string

Filter by one or more concept classes (comma-separated).

Filters can exclude relevant concepts. Apply them only when the expected vocabulary, domain, or concept type is known.

string

Vocabulary version (e.g., 2025v2). Uses default if not specified.

curl -X GET "https://api.omophub.com/v1/search/semantic?query=heart%20attack&page_size=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "query": "heart attack",
    "results": [
      {
        "concept_id": 4329847,
        "concept_name": "Myocardial infarction",
        "domain_id": "Condition",
        "vocabulary_id": "SNOMED",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "concept_code": "22298006",
        "similarity_score": 0.92,
        "matched_text": "Myocardial infarction"
      }
    ],
    "total_results": 45,
    "retrieval_truncated": false,
    "totals_are_lower_bound": false,
    "latency_ms": 28
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 45,
      "total_pages": 3,
      "has_next": true,
      "has_previous": false
    },
    "request_id": "req_sem_abc123"
  }
}

Response Fields

Data Object

boolean

Whether semantic search completed.

object

Semantic results and query metadata.

object

Request, release, and pagination metadata.

string

Original search query

array

Matching concept suggestions, ordered by similarity.

integer

Number of matching concepts found. Check totals_are_lower_bound to determine whether the value is exact.

boolean

true when additional matching concepts may exist beyond those returned.

boolean

true when the reported totals are minimum known values rather than exact counts.

number

Processing time in milliseconds

Result Object

integer

OMOP concept_id

string

Primary name of the returned OMOP concept. The concept may be Standard, Classification, or non-Standard; inspect standard_concept.

number

Relative match score from 0.0 to 1.0. Higher values rank first. It is not a probability or clinical confidence value.

string

Text associated with the match.

string

OMOP domain (e.g., Condition, Drug, Procedure)

string

Source vocabulary (e.g., SNOMED, ICD10CM, RxNorm)

string

Concept classification within the vocabulary

string | null

Standard concept flag: S (Standard), C (Classification), or null

string

Original code from the source vocabulary

Pagination Object (in meta)

integer

Current page number

integer

Number of results per page

integer

Approximate total number of matching items (lower bound). Use has_next for reliable pagination.

integer

Approximate total number of pages. Use has_next to determine if more pages exist.

boolean

Whether the client should request the next page.

boolean

Reliable indicator of whether previous pages exist.

When totals_are_lower_bound is true, use has_next for pagination rather than comparing page with total_pages.

Usage Notes

Review the returned concept, domain, vocabulary, and Standard status before using a result in a clinical workflow.
Use threshold to narrow results, but do not interpret the score as clinical confidence.
Use concept mappings when you need to convert a selected source concept to an OMOP Standard concept.

Basic Concept Search - Keyword-based search
Similar Concepts - Find concepts similar to a given concept
Autocomplete - Type-ahead suggestions

Use /search/similar when you want to start from an existing concept_id.

API Reference

Search

Concepts

Concept Hierarchy

Mappings

FHIR Resolver

Relationships

Domains & Classifications

Vocabularies

Overview

When to Use Semantic Search

Query Parameters

Response Fields

Data Object

Result Object

Usage Notes

​Overview

​When to Use Semantic Search

​Query Parameters

​Response Fields

​Data Object

​Result Object

​Pagination Object (in meta)

​Usage Notes

​Related Endpoints

Overview

When to Use Semantic Search

Query Parameters

Response Fields

Data Object

Result Object

Pagination Object (in meta)

Usage Notes

Related Endpoints