Bulk Semantic Search - OMOPHub.com API

curl -X POST "https://api.omophub.com/v1/search/semantic-bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaults": {
      "vocabulary_ids": ["SNOMED"],
      "standard_concept": "S",
      "threshold": 0.5,
      "page_size": 5
    },
    "searches": [
      {
        "search_id": "s1",
        "query": "heart attack"
      },
      {
        "search_id": "s2",
        "query": "sugar diabetes",
        "threshold": 0.7
      },
      {
        "search_id": "s3",
        "query": "aspirin tablets",
        "vocabulary_ids": ["RxNorm"],
        "domain_ids": ["Drug"]
      }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      {
        "search_id": "s1",
        "query": "heart attack",
        "status": "completed",
        "results": [
          {
            "concept_id": 4329847,
            "concept_name": "Myocardial infarction",
            "concept_code": "22298006",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "similarity_score": 0.92,
            "matched_text": "Myocardial infarction"
          },
          {
            "concept_id": 434376,
            "concept_name": "Acute myocardial infarction",
            "concept_code": "57054005",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "similarity_score": 0.89,
            "matched_text": "Acute myocardial infarction"
          }
        ],
        "similarity_threshold": 0.5,
        "result_count": 2,
        "duration": 45,
        "query_enhancement": null
      },
      {
        "search_id": "s2",
        "query": "sugar diabetes",
        "status": "completed",
        "results": [
          {
            "concept_id": 201826,
            "concept_name": "Type 2 diabetes mellitus",
            "concept_code": "44054006",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "similarity_score": 0.88,
            "matched_text": "Type 2 diabetes mellitus"
          },
          {
            "concept_id": 4000678,
            "concept_name": "Diabetes mellitus",
            "concept_code": "73211009",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "similarity_score": 0.85,
            "matched_text": "Diabetes mellitus"
          }
        ],
        "similarity_threshold": 0.7,
        "result_count": 2,
        "duration": 38,
        "query_enhancement": null
      },
      {
        "search_id": "s3",
        "query": "aspirin tablets",
        "status": "completed",
        "results": [
          {
            "concept_id": 1112807,
            "concept_name": "Aspirin",
            "concept_code": "1191",
            "vocabulary_id": "RxNorm",
            "domain_id": "Drug",
            "concept_class_id": "Ingredient",
            "standard_concept": "S",
            "similarity_score": 0.94,
            "matched_text": "Aspirin"
          }
        ],
        "similarity_threshold": 0.5,
        "result_count": 1,
        "duration": 32,
        "query_enhancement": null
      }
    ],
    "total_searches": 3,
    "completed_count": 3,
    "failed_count": 0,
    "total_duration": 156
  },
  "meta": {
    "request_id": "req_sem_bulk_abc123",
    "vocab_release": "2025.2",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

curl -X POST "https://api.omophub.com/v1/search/semantic-bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaults": {
      "vocabulary_ids": ["SNOMED"],
      "standard_concept": "S",
      "threshold": 0.5,
      "page_size": 5
    },
    "searches": [
      {
        "search_id": "s1",
        "query": "heart attack"
      },
      {
        "search_id": "s2",
        "query": "sugar diabetes",
        "threshold": 0.7
      },
      {
        "search_id": "s3",
        "query": "aspirin tablets",
        "vocabulary_ids": ["RxNorm"],
        "domain_ids": ["Drug"]
      }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      {
        "search_id": "s1",
        "query": "heart attack",
        "status": "completed",
        "results": [
          {
            "concept_id": 4329847,
            "concept_name": "Myocardial infarction",
            "concept_code": "22298006",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "similarity_score": 0.92,
            "matched_text": "Myocardial infarction"
          },
          {
            "concept_id": 434376,
            "concept_name": "Acute myocardial infarction",
            "concept_code": "57054005",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "similarity_score": 0.89,
            "matched_text": "Acute myocardial infarction"
          }
        ],
        "similarity_threshold": 0.5,
        "result_count": 2,
        "duration": 45,
        "query_enhancement": null
      },
      {
        "search_id": "s2",
        "query": "sugar diabetes",
        "status": "completed",
        "results": [
          {
            "concept_id": 201826,
            "concept_name": "Type 2 diabetes mellitus",
            "concept_code": "44054006",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "similarity_score": 0.88,
            "matched_text": "Type 2 diabetes mellitus"
          },
          {
            "concept_id": 4000678,
            "concept_name": "Diabetes mellitus",
            "concept_code": "73211009",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "similarity_score": 0.85,
            "matched_text": "Diabetes mellitus"
          }
        ],
        "similarity_threshold": 0.7,
        "result_count": 2,
        "duration": 38,
        "query_enhancement": null
      },
      {
        "search_id": "s3",
        "query": "aspirin tablets",
        "status": "completed",
        "results": [
          {
            "concept_id": 1112807,
            "concept_name": "Aspirin",
            "concept_code": "1191",
            "vocabulary_id": "RxNorm",
            "domain_id": "Drug",
            "concept_class_id": "Ingredient",
            "standard_concept": "S",
            "similarity_score": 0.94,
            "matched_text": "Aspirin"
          }
        ],
        "similarity_threshold": 0.5,
        "result_count": 1,
        "duration": 32,
        "query_enhancement": null
      }
    ],
    "total_searches": 3,
    "completed_count": 3,
    "failed_count": 0,
    "total_duration": 156
  },
  "meta": {
    "request_id": "req_sem_bulk_abc123",
    "vocab_release": "2025.2",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Overview

This endpoint allows you to submit multiple semantic search queries in a single request, combining the power of vector similarity matching with efficient batch processing. We host a vector similarity service and do not use third party services for this. It’s ideal for processing clinical notes, batch NLP pipelines, or any workflow requiring high-confidence concept matching across many terms. Each query uses vector similarity search with a default limit of 10 results per query (configurable via page_size, max 50). Up to 25 queries can be submitted per request.

Request Body

searches

array

required

Array of semantic search query objects (1-25 items)

Show Search Object

search_id

string

required

Unique identifier for this search within the batch

query

string

required

Natural language search query (1-500 characters)

page_size

integer

default:"10"

Number of results per search (1-50). Overrides defaults.page_size for this search.

threshold

number

default:"0.5"

Minimum similarity score (0.0-1.0). Higher values = stricter matching. Overrides defaults.threshold for this search.

vocabulary_ids

string[]

Filter results to specific vocabularies (e.g., ["SNOMED", "ICD10CM"]). Overrides defaults.vocabulary_ids for this search.

domain_ids

string[]

Filter results to specific domains (e.g., ["Condition", "Drug"]). Overrides defaults.domain_ids for this search.

standard_concept

string

Filter by standard concept status: "S" (Standard) or "C" (Classification). Overrides defaults.standard_concept for this search.

concept_class_id

string

Filter by concept class (e.g., "Clinical Finding"). Overrides defaults.concept_class_id for this search.

defaults

object

Default parameters applied to all searches. Individual searches can override any default.

Show Defaults Object

page_size

integer

default:"10"

Default results per search (1-50)

threshold

number

default:"0.5"

Default minimum similarity score (0.0-1.0)

vocabulary_ids

string[]

Default vocabulary filter for all searches (e.g., ["SNOMED"])

domain_ids

string[]

Default domain filter for all searches (e.g., ["Condition"])

standard_concept

string

Default standard concept filter: "S" or "C"

concept_class_id

string

Default concept class filter

Query Parameters

vocab_release

string

Specific vocabulary release version (defaults to latest)

Response

success

boolean

Indicates if the request was successful

data

object

Response data object containing results and summary counts

Show Data Object

results

array

Array of search results, one per query

Show Search Result

search_id

string

Identifier matching the request’s search_id

query

string

Original search query

status

string

Query execution status: completed or failed

results

array

Array of matching concepts with similarity scores

Show Concept Result

concept_id

integer

Unique concept identifier

concept_name

string

Primary concept name

concept_code

string

Concept code from source vocabulary

vocabulary_id

string

Source vocabulary

domain_id

string

Domain classification

concept_class_id

string

Concept class

standard_concept

string | null

Standard concept indicator: S, C, or null

similarity_score

number

Semantic similarity score (0.0-1.0). Higher = more similar.

matched_text

string

The text that matched (concept name or synonym)

error

string

Error message (only present if query failed)

similarity_threshold

number

The similarity threshold used for this query

result_count

integer

Number of results returned for this query

duration

number

Processing time for this query in milliseconds

query_enhancement

object | null

Query enhancement details (only present if query was modified)

Show Query Enhancement

original_query

string

Original query before enhancement

enhanced_query

string

Enhanced query used for search

abbreviations_expanded

string[]

List of abbreviations that were expanded

misspellings_corrected

string[]

List of misspellings that were corrected

total_searches

integer

Total number of searches in the request

completed_count

integer

Number of successfully completed searches

failed_count

integer

Number of failed searches

total_duration

number

Total processing time in milliseconds

meta

object

Show Metadata

request_id

string

Unique identifier for the request

vocab_release

string

Vocabulary release version used

timestamp

string

Request timestamp

curl -X POST "https://api.omophub.com/v1/search/semantic-bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaults": {
      "vocabulary_ids": ["SNOMED"],
      "standard_concept": "S",
      "threshold": 0.5,
      "page_size": 5
    },
    "searches": [
      {
        "search_id": "s1",
        "query": "heart attack"
      },
      {
        "search_id": "s2",
        "query": "sugar diabetes",
        "threshold": 0.7
      },
      {
        "search_id": "s3",
        "query": "aspirin tablets",
        "vocabulary_ids": ["RxNorm"],
        "domain_ids": ["Drug"]
      }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      {
        "search_id": "s1",
        "query": "heart attack",
        "status": "completed",
        "results": [
          {
            "concept_id": 4329847,
            "concept_name": "Myocardial infarction",
            "concept_code": "22298006",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "similarity_score": 0.92,
            "matched_text": "Myocardial infarction"
          },
          {
            "concept_id": 434376,
            "concept_name": "Acute myocardial infarction",
            "concept_code": "57054005",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "similarity_score": 0.89,
            "matched_text": "Acute myocardial infarction"
          }
        ],
        "similarity_threshold": 0.5,
        "result_count": 2,
        "duration": 45,
        "query_enhancement": null
      },
      {
        "search_id": "s2",
        "query": "sugar diabetes",
        "status": "completed",
        "results": [
          {
            "concept_id": 201826,
            "concept_name": "Type 2 diabetes mellitus",
            "concept_code": "44054006",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "similarity_score": 0.88,
            "matched_text": "Type 2 diabetes mellitus"
          },
          {
            "concept_id": 4000678,
            "concept_name": "Diabetes mellitus",
            "concept_code": "73211009",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "similarity_score": 0.85,
            "matched_text": "Diabetes mellitus"
          }
        ],
        "similarity_threshold": 0.7,
        "result_count": 2,
        "duration": 38,
        "query_enhancement": null
      },
      {
        "search_id": "s3",
        "query": "aspirin tablets",
        "status": "completed",
        "results": [
          {
            "concept_id": 1112807,
            "concept_name": "Aspirin",
            "concept_code": "1191",
            "vocabulary_id": "RxNorm",
            "domain_id": "Drug",
            "concept_class_id": "Ingredient",
            "standard_concept": "S",
            "similarity_score": 0.94,
            "matched_text": "Aspirin"
          }
        ],
        "similarity_threshold": 0.5,
        "result_count": 1,
        "duration": 32,
        "query_enhancement": null
      }
    ],
    "total_searches": 3,
    "completed_count": 3,
    "failed_count": 0,
    "total_duration": 156
  },
  "meta": {
    "request_id": "req_sem_bulk_abc123",
    "vocab_release": "2025.2",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Key Differences from Bulk Search

Feature	Bulk Semantic Search	Bulk Search
Search method	Vector similarity (embeddings)	Full-text keyword matching
Score field	`similarity_score` (0.0-1.0)	`search_score` (relevance rank)
Max queries	25 per request	50 per request
Max page_size	50	100
Threshold parameter	Yes (filters by similarity)	No
Query enhancement	Yes (abbreviation expansion, typo correction)	No
Response shape	`data` (object with results array and summary)	`data` (direct array)

Use Cases

Clinical Notes Processing

Process extracted terms from clinical notes in batch:

# Terms extracted from clinical notes via NLP
clinical_terms = [
    "chest pain radiating to left arm",
    "shortness of breath on exertion",
    "elevated troponin levels",
    "irregular heartbeat"
]

payload = {
    "defaults": {
        "vocabulary_ids": ["SNOMED"],
        "domain_ids": ["Condition", "Observation"],
        "standard_concept": "S",
        "threshold": 0.6
    },
    "searches": [
        {"search_id": f"note_{i}", "query": term}
        for i, term in enumerate(clinical_terms)
    ]
}

response = requests.post(
    "https://api.omophub.com/v1/search/semantic-bulk",
    headers=headers,
    json=payload
)

High-Confidence Batch Matching

Use a high threshold for automated mapping pipelines where accuracy is critical:

payload = {
    "defaults": {
        "threshold": 0.8,
        "standard_concept": "S",
        "page_size": 3
    },
    "searches": [
        {"search_id": "dx1", "query": "heart attack"},
        {"search_id": "dx2", "query": "high blood pressure"},
        {"search_id": "dx3", "query": "sugar diabetes"}
    ]
}

Multi-Domain Batch Search

Search across different domains in a single request using per-search overrides:

payload = {
    "defaults": {"standard_concept": "S", "threshold": 0.5},
    "searches": [
        {
            "search_id": "cond1",
            "query": "chest pain",
            "domain_ids": ["Condition"],
            "vocabulary_ids": ["SNOMED"]
        },
        {
            "search_id": "drug1",
            "query": "blood thinner medication",
            "domain_ids": ["Drug"],
            "vocabulary_ids": ["RxNorm"]
        },
        {
            "search_id": "lab1",
            "query": "blood sugar test",
            "domain_ids": ["Measurement"],
            "vocabulary_ids": ["LOINC"]
        }
    ]
}

Error Handling

Per-Query Failure Isolation

Each query in the batch is processed independently. Failed queries do not affect other queries:

{
  "success": true,
  "data": {
    "results": [
      {
        "search_id": "s1",
        "query": "heart attack",
        "status": "completed",
        "results": [...],
        "similarity_threshold": 0.5,
        "result_count": 5,
        "duration": 42,
        "query_enhancement": null
      },
      {
        "search_id": "s2",
        "query": "",
        "status": "failed",
        "results": [],
        "error": "Search query is required",
        "similarity_threshold": 0.5,
        "result_count": 0,
        "duration": 1,
        "query_enhancement": null
      }
    ],
    "total_searches": 2,
    "completed_count": 1,
    "failed_count": 1,
    "total_duration": 48
  }
}

Semantic Search - Single query semantic search with pagination
Bulk Search - Keyword-based bulk search (up to 50 queries)
Basic Search - Single query keyword search with pagination
Similar Concepts - Find concepts similar to a given concept

Bulk Search Search Similar Concepts

​Overview

​Request Body

​Query Parameters

​Response

​Key Differences from Bulk Search

​Use Cases

​Clinical Notes Processing

​High-Confidence Batch Matching

​Multi-Domain Batch Search

​Error Handling

​Per-Query Failure Isolation

​Related Endpoints

Overview

Request Body

Query Parameters

Response

Key Differences from Bulk Search

Use Cases

Clinical Notes Processing

High-Confidence Batch Matching

Multi-Domain Batch Search

Error Handling

Per-Query Failure Isolation

Related Endpoints