Skip to main content
curl -X POST "https://api.omophub.com/v1/search/advanced" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "diabetes mellitus type 2",
    "page_size": 10
  }'

{
  "success": true,
  "data": {
    "concepts": [
      {
        "concept_id": 201826,
        "concept_name": "Type 2 diabetes mellitus",
        "concept_code": "44054006",
        "vocabulary_id": "SNOMED",
        "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null,
        "relevance_score": 0.953
      },
      {
        "concept_id": 435216,
        "concept_name": "Diabetes mellitus type 2 in obese",
        "concept_code": "E11.0",
        "vocabulary_id": "ICD10CM",
        "vocabulary_name": "International Classification of Diseases, Tenth Revision, Clinical Modification",
        "domain_id": "Condition",
        "concept_class_id": "4-char billing code",
        "standard_concept": null,
        "valid_start_date": "2015-10-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null,
        "relevance_score": 0.847
      }
    ],
    "facets": {
      "vocabularies": [
        {"vocabulary_id": "SNOMED", "vocabulary_name": "SNOMED CT", "count": 45},
        {"vocabulary_id": "ICD10CM", "vocabulary_name": "ICD-10-CM", "count": 23},
        {"vocabulary_id": "ICD9CM", "vocabulary_name": "ICD-9-CM", "count": 12}
      ],
      "domains": [
        {"domain_id": "Condition", "domain_name": "Condition", "count": 67},
        {"domain_id": "Observation", "domain_name": "Observation", "count": 13}
      ],
      "concept_classes": [
        {"concept_class_id": "Clinical Finding", "count": 45},
        {"concept_class_id": "4-char billing code", "count": 23}
      ]
    },
    "search_metadata": {
      "query_time_ms": 127,
      "total_results": 80,
      "max_relevance_score": 0.953,
      "search_algorithm": "full_text_with_ranking"
    }
  },
  "meta": {
    "request_id": "req_adv_search_abc123",
    "timestamp": "2024-01-15T10:30:00Z",
    "vocab_release": "2025.1",
    "search": {
      "query": "diabetes mellitus type 2",
      "total_results": 80,
      "filters_applied": {
        "vocabulary_ids": [],
        "domain_ids": [],
        "standard_concepts_only": true
      }
    },
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total_items": 80,
      "total_pages": 8,
      "has_next": true,
      "has_previous": false
    }
  }
}

​
Overview

The advanced search endpoint provides powerful multi-criteria search capabilities across healthcare vocabularies. Use complex queries, filters, and ranking to find the most relevant medical concepts.
Best for: Complex search scenarios requiring multiple filters, specific vocabularies, or advanced ranking criteria.
Query Requirements: Queries must be at least 3 characters long OR include at least one filter (vocabulary_ids, domain_ids, or concept_class_ids). This prevents overly broad searches that could timeout.

​
Endpoint

​
POST
string
/v1/search/advanced

​
Authentication

​
Authorization
string
required
Bearer token with your API key

​
Request Body

​
query
string
required
The search query termExample: "diabetes mellitus type 2"Validation: Query must be at least 3 characters long, OR include at least one filter (vocabulary_ids, domain_ids, or concept_class_ids). Short queries without filters are rejected to prevent performance issues.
​
vocabulary_ids
array
Array of vocabulary IDs to search withinOptions: SNOMED, ICD10CM, ICD9CM, RxNorm, LOINC, HCPCS, etc.Default: All vocabularies
​
domain_ids
array
Array of domain IDs to filter byOptions: Condition, Drug, Procedure, Measurement, Observation, etc.
​
concept_class_ids
array
Array of concept class IDs to filter byExamples: Clinical Finding, Pharmaceutical Substance, Procedure
​
standard_concepts_only
boolean
default:true
Whether to include only standard concepts
​
include_invalid
boolean
default:true
Whether to include invalid/deprecated concepts
​
relationship_filters
array
Array of relationship filter objects
[{
  "relationship_id": "Maps to",
  "target_vocabularies": ["SNOMED"],
  "required": true
}]
​
date_range
object
Filter by validity date range
{
  "start_date": "2020-01-01",
  "end_date": "2024-12-31"
}
​
page
integer
default:1
Page number (1-based indexing)
​
page_size
integer
default:20
Number of results per page (max: 1000)

​
Response

​
success
boolean
Whether the request was successful
​
data
object
​
meta
object
Response metadata including pagination

​
Examples

curl -X POST "https://api.omophub.com/v1/search/advanced" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "diabetes mellitus type 2",
    "page_size": 10
  }'

{
  "success": true,
  "data": {
    "concepts": [
      {
        "concept_id": 201826,
        "concept_name": "Type 2 diabetes mellitus",
        "concept_code": "44054006",
        "vocabulary_id": "SNOMED",
        "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null,
        "relevance_score": 0.953
      },
      {
        "concept_id": 435216,
        "concept_name": "Diabetes mellitus type 2 in obese",
        "concept_code": "E11.0",
        "vocabulary_id": "ICD10CM",
        "vocabulary_name": "International Classification of Diseases, Tenth Revision, Clinical Modification",
        "domain_id": "Condition",
        "concept_class_id": "4-char billing code",
        "standard_concept": null,
        "valid_start_date": "2015-10-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null,
        "relevance_score": 0.847
      }
    ],
    "facets": {
      "vocabularies": [
        {"vocabulary_id": "SNOMED", "vocabulary_name": "SNOMED CT", "count": 45},
        {"vocabulary_id": "ICD10CM", "vocabulary_name": "ICD-10-CM", "count": 23},
        {"vocabulary_id": "ICD9CM", "vocabulary_name": "ICD-9-CM", "count": 12}
      ],
      "domains": [
        {"domain_id": "Condition", "domain_name": "Condition", "count": 67},
        {"domain_id": "Observation", "domain_name": "Observation", "count": 13}
      ],
      "concept_classes": [
        {"concept_class_id": "Clinical Finding", "count": 45},
        {"concept_class_id": "4-char billing code", "count": 23}
      ]
    },
    "search_metadata": {
      "query_time_ms": 127,
      "total_results": 80,
      "max_relevance_score": 0.953,
      "search_algorithm": "full_text_with_ranking"
    }
  },
  "meta": {
    "request_id": "req_adv_search_abc123",
    "timestamp": "2024-01-15T10:30:00Z",
    "vocab_release": "2025.1",
    "search": {
      "query": "diabetes mellitus type 2",
      "total_results": 80,
      "filters_applied": {
        "vocabulary_ids": [],
        "domain_ids": [],
        "standard_concepts_only": true
      }
    },
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total_items": 80,
      "total_pages": 8,
      "has_next": true,
      "has_previous": false
    }
  }
}

curl -X POST "https://api.omophub.com/v1/search/advanced" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "hypertension",
    "vocabulary_ids": ["SNOMED", "ICD10CM"],
    "domain_ids": ["Condition"],
    "standard_concepts_only": true,
    "date_range": {
      "start_date": "2020-01-01",
      "end_date": "2024-12-31"
    },
    "page_size": 20
  }'

​
Complex Relationship Filtering

curl -X POST "https://api.omophub.com/v1/search/advanced" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "insulin",
    "vocabulary_ids": ["RxNorm"],
    "domain_ids": ["Drug"],
    "relationship_filters": [
      {
        "relationship_id": "RxNorm has dose form",
        "target_vocabularies": ["RxNorm"],
        "required": true
      }
    ],
    "concept_class_ids": ["Clinical Drug"],
    "page_size": 15
  }'

​
Search Features

​
Full-Text Search

  • Multi-field search: Searches concept names, synonyms, and descriptions
  • Phrase matching: Use quotes for exact phrases: "myocardial infarction"
  • Wildcard support: Use * for partial matching: diabet*
  • Boolean operators: Use AND, OR, NOT: diabetes AND type 2

​
Relevance Scoring

Results are ranked by relevance using:
  1. Exact matches: Exact concept name matches score highest
  2. Phrase matches: Complete phrase matches in names or synonyms
  3. Term frequency: Frequency of query terms in concept text
  4. Vocabulary priority: Standard concepts ranked higher
  5. Clinical relevance: Healthcare-specific ranking adjustments
Use facets to understand result distribution: 
# Access facets for filtering insights
facets = results.data.facets

print("Available vocabularies:")
for vocab in facets.vocabularies:
    print(f"  {vocab.vocabulary_name}: {vocab.count} concepts")

print("\nAvailable domains:")
for domain in facets.domains:
    print(f"  {domain.domain_name}: {domain.count} concepts")

​
Performance Tips

  1. Use specific vocabulary_ids: Limit search to relevant vocabularies only
  2. Filter by domain_ids: Reduce result set with domain filters
  3. Reasonable page sizes: Use page_size of 20-100 for best performance
  4. Cache results: Cache frequently accessed searches
  5. Use standard concepts: Set standard_concepts_only: true for faster queries
  6. Avoid broad queries: Short queries (< 3 characters) without filters are rejected. Use more specific terms or add filters for better results.

Basic Search

Simple concept search with minimal parameters

Search Autocomplete

Real-time search suggestions

Similar Concepts

Find semantically similar concepts

Search Facets

Get available search facets