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"]
}
]
}'
import { OMOPHub } from '@omophub/omophub-node';
const client = new OMOPHub();
// Per-search entries use snake_case (pass-through to the bulk API).
const { data } = await client.search.bulkSemantic(
[
{ 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'] },
],
{ defaults: { vocabulary_ids: ['SNOMED'], standard_concept: 'S', threshold: 0.5, page_size: 5 } },
);
import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
payload = {
'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']
}
]
}
response = requests.post(
'https://api.omophub.com/v1/search/semantic-bulk',
headers=headers,
json=payload
)
data = response.json()
{
"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"
}
}
Bulk Semantic Search
Perform semantic OMOP concept search on multiple natural-language queries simultaneously with optimized batch processing for LLM and AI workflows.
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"]
}
]
}'
import { OMOPHub } from '@omophub/omophub-node';
const client = new OMOPHub();
// Per-search entries use snake_case (pass-through to the bulk API).
const { data } = await client.search.bulkSemantic(
[
{ 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'] },
],
{ defaults: { vocabulary_ids: ['SNOMED'], standard_concept: 'S', threshold: 0.5, page_size: 5 } },
);
import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
payload = {
'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']
}
]
}
response = requests.post(
'https://api.omophub.com/v1/search/semantic-bulk',
headers=headers,
json=payload
)
data = response.json()
{
"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 viapage_size, max 50). Up to 25 queries can be submitted per request.
Request Body
array
required
Array of semantic search query objects (1-25 items)
Show Search Object
Show Search Object
string
required
Unique identifier for this search within the batch
string
required
Natural language search query (1-500 characters)
integer
default:"10"
Number of results per search (1-50). Overrides
defaults.page_size for this search.number
default:"0.5"
Minimum similarity score (0.0-1.0). Higher values = stricter matching. Overrides
defaults.threshold for this search.string[]
Filter results to specific vocabularies (e.g.,
["SNOMED", "ICD10CM"]). Overrides defaults.vocabulary_ids for this search.string[]
Filter results to specific domains (e.g.,
["Condition", "Drug"]). Overrides defaults.domain_ids for this search.string
Filter by standard concept status:
"S" (Standard) or "C" (Classification). Overrides defaults.standard_concept for this search.string
Filter by concept class (e.g.,
"Clinical Finding"). Overrides defaults.concept_class_id for this search.object
Default parameters applied to all searches. Individual searches can override any default.
Show Defaults Object
Show Defaults Object
integer
default:"10"
Default results per search (1-50)
number
default:"0.5"
Default minimum similarity score (0.0-1.0)
string[]
Default vocabulary filter for all searches (e.g.,
["SNOMED"])string[]
Default domain filter for all searches (e.g.,
["Condition"])string
Default standard concept filter:
"S" or "C"string
Default concept class filter
Query Parameters
string
Specific vocabulary release version (defaults to latest)
Response
boolean
Indicates if the request was successful
object
Response data object containing results and summary counts
Show Data Object
Show Data Object
array
Array of search results, one per query
Show Search Result
Show Search Result
string
Identifier matching the request’s search_id
string
Original search query
string
Query execution status:
completed or failedarray
Array of matching concepts with similarity scores
Show Concept Result
Show Concept Result
integer
Unique concept identifier
string
Primary concept name
string
Concept code from source vocabulary
string
Source vocabulary
string
Domain classification
string
Concept class
string | null
Standard concept indicator:
S, C, or nullnumber
Semantic similarity score (0.0-1.0). Higher = more similar.
string
The text that matched (concept name or synonym)
string
Error message (only present if query failed)
number
The similarity threshold used for this query
integer
Number of results returned for this query
number
Processing time for this query in milliseconds
integer
Total number of searches in the request
integer
Number of successfully completed searches
integer
Number of failed searches
number
Total processing time in milliseconds
object
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"]
}
]
}'
import { OMOPHub } from '@omophub/omophub-node';
const client = new OMOPHub();
// Per-search entries use snake_case (pass-through to the bulk API).
const { data } = await client.search.bulkSemantic(
[
{ 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'] },
],
{ defaults: { vocabulary_ids: ['SNOMED'], standard_concept: 'S', threshold: 0.5, page_size: 5 } },
);
import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
payload = {
'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']
}
]
}
response = requests.post(
'https://api.omophub.com/v1/search/semantic-bulk',
headers=headers,
json=payload
)
data = response.json()
{
"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
}
}
Related Endpoints
- 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
Was this page helpful?
⌘I