Skip to main content
GET
https://api.omophub.com
/
v1
/
concepts
/
search
/
facets
curl -X GET "https://api.omophub.com/v1/concepts/search/facets?query=diabetes&vocabulary_ids=SNOMED,ICD10CM&facet_types=vocabulary,domain,concept_class&include_counts=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "facets": {
      "vocabularies": [
        {
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
          "concept_count": 245
        },
        {
          "vocabulary_id": "ICD10CM",
          "vocabulary_name": "ICD-10 Clinical Modification",
          "concept_count": 67
        }
      ],
      "domains": [
        {
          "domain_id": "Condition",
          "domain_name": "Condition",
          "concept_count": 198
        },
        {
          "domain_id": "Procedure",
          "domain_name": "Procedure",
          "concept_count": 87
        },
        {
          "domain_id": "Drug",
          "domain_name": "Drug",
          "concept_count": 27
        }
      ],
      "concept_classes": [
        {
          "concept_class_id": "Clinical Finding",
          "concept_class_name": "Clinical Finding",
          "concept_count": 156
        },
        {
          "concept_class_id": "Procedure",
          "concept_class_name": "Procedure",
          "concept_count": 87
        }
      ]
    },
    "query_info": {
      "original_query": "diabetes",
      "total_concepts": 312,
      "faceted_concepts": 312
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 312,
      "total_pages": 16,
      "has_next": true,
      "has_previous": false
    }
  }
}

​
Overview

This endpoint provides faceted search capabilities specifically for medical concept searches. It returns structured filters and categories that help users refine their concept search queries across multiple dimensions such as domains, vocabularies, concept classes, and clinical attributes.

​
Query Parameters

​
query
string
Base concept search query to generate relevant facets for
​
vocabulary_ids
string
Target vocabularies for facet generation (comma-separated)
Examples: SNOMED, ICD10CM,LOINC, RXNORM,NDC
​
domain_ids
string
Filter facets to specific clinical domains (comma-separated)
Examples: Condition,Procedure, Drug,Device
​
concept_class_ids
string
Filter facets to specific concept classes (comma-separated)
Examples: Clinical Finding,Procedure, Ingredient,Brand Name
​
standard_concept
string
Filter to standard concepts only
Options: S (standard), C (classification), N (non-standard)
​
include_invalid
boolean
default:"false"
Include invalid/deprecated concepts in facet counts
​
facet_types
string
default:"vocabulary,domain,concept_class"
Types of facets to include (comma-separated)
Options: vocabulary, domain, concept_class
​
include_counts
boolean
default:"true"
Include concept counts for each facet value
​
max_facet_values
integer
default:"20"
Maximum number of values per facet type
​
page_size
integer
default:"20"
Number of results per page
​
page
integer
default:"1"
Page number for pagination

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
Contains the faceted search results for concepts
​
meta
object
Response metadata including pagination and performance info
curl -X GET "https://api.omophub.com/v1/concepts/search/facets?query=diabetes&vocabulary_ids=SNOMED,ICD10CM&facet_types=vocabulary,domain,concept_class&include_counts=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "facets": {
      "vocabularies": [
        {
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
          "concept_count": 245
        },
        {
          "vocabulary_id": "ICD10CM",
          "vocabulary_name": "ICD-10 Clinical Modification",
          "concept_count": 67
        }
      ],
      "domains": [
        {
          "domain_id": "Condition",
          "domain_name": "Condition",
          "concept_count": 198
        },
        {
          "domain_id": "Procedure",
          "domain_name": "Procedure",
          "concept_count": 87
        },
        {
          "domain_id": "Drug",
          "domain_name": "Drug",
          "concept_count": 27
        }
      ],
      "concept_classes": [
        {
          "concept_class_id": "Clinical Finding",
          "concept_class_name": "Clinical Finding",
          "concept_count": 156
        },
        {
          "concept_class_id": "Procedure",
          "concept_class_name": "Procedure",
          "concept_count": 87
        }
      ]
    },
    "query_info": {
      "original_query": "diabetes",
      "total_concepts": 312,
      "faceted_concepts": 312
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 312,
      "total_pages": 16,
      "has_next": true,
      "has_previous": false
    }
  }
}

​
Usage Examples

​
Basic Concept Search Facets

Get facets for a diabetes-related concept search: 
GET /v1/concepts/search/facets?query=diabetes&vocabulary_ids=SNOMED
Generate facets across multiple medical vocabularies: 
GET /v1/concepts/search/facets?query=hypertension&vocabulary_ids=SNOMED,ICD10CM,LOINC&facet_types=vocabulary,domain,concept_class

​
Domain-Specific Facets

Get facets filtered to specific clinical domains: 
GET /v1/concepts/search/facets?query=medication&domain_ids=Drug&facet_types=vocabulary,concept_class&max_facet_values=50