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"
}
],
"similarity_threshold": 0.5,
"result_count": 1,
"retrieval_truncated": false,
"totals_are_lower_bound": false,
"duration": 45
}
],
"total_searches": 1,
"completed_count": 1,
"failed_count": 0,
"total_duration": 45
}
}
Bulk Semantic Search
Find related OMOP concepts for multiple English-language queries in one request.
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"
}
],
"similarity_threshold": 0.5,
"result_count": 1,
"retrieval_truncated": false,
"totals_are_lower_bound": false,
"duration": 45
}
],
"total_searches": 1,
"completed_count": 1,
"failed_count": 0,
"total_duration": 45
}
}
Overview
Find related OMOP concepts for up to 25 English-language queries in one request. Each query is processed independently and can override the shared defaults. Results are suggestions for review, not automatic clinical coding decisions.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. NUL characters (U+0000)
are stripped before processing; results echo the normalized identifier.
The identifier must remain nonempty after normalization.
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 fail only their own bulk item.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 return fewer, closer
matches. Overrides
defaults.threshold for this search.string[]
Filter results to specific vocabularies (e.g.,
["SNOMED", "ICD10CM"]).
In a mixed list, inaccessible vocabularies are omitted; an
all-inaccessible list fails that search item. Overrides
defaults.vocabulary_ids.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). This is not a probability or
clinical confidence threshold.
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
Matching concept suggestions, ordered by similarity.
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
Relative match score from 0.0 to 1.0. Relevance remains primary,
but within an anchored score band of at most
0.0025 the API may
prefer more clinically useful concepts and demote non-clinical
concept classes. Scores are therefore not guaranteed to be
strictly descending. The score is not a probability or clinical
confidence value.string
Text associated with the match.
string
Error message (only present if query failed)
number
The similarity threshold used for this query
integer
Number of results returned for this query
boolean
true when additional matching concepts may exist beyond those
returned.boolean
true when reported totals are minimum known values rather than exact
counts. result_count remains the exact number returned for this
item.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
Review each result before using it in a clinical workflow. Similarity scores
rank matches; they are not probabilities or clinical confidence values.
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"
}
],
"similarity_threshold": 0.5,
"result_count": 1,
"retrieval_truncated": false,
"totals_are_lower_bound": false,
"duration": 45
}
],
"total_searches": 1,
"completed_count": 1,
"failed_count": 0,
"total_duration": 45
}
}
Error Handling
Each query is processed independently. A failed item hasstatus: "failed"
and an error message; other valid items continue normally.
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?