Search Facets - OMOPHub.com API

curl -X GET "https://api.omophub.com/v1/search/facets?query=diabetes&facet_types=vocabulary,domain,concept_class,specialty&include_counts=true&include_percentages=true&max_facet_values=20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "query": "diabetes",
    "facet_metadata": {
      "total_concepts": 1247,
      "facet_types_included": [
        "vocabulary",
        "domain", 
        "concept_class",
        "specialty"
      ],
      "facet_depth": "standard",
      "generation_time_ms": 234,
      "context_applied": {
        "medical_context": null,
        "user_context": null,
        "temporal_scope": "current"
      }
    },
    "facets": {
      "vocabulary": {
        "facet_type": "vocabulary",
        "display_name": "Medical Vocabularies",
        "description": "Source vocabularies containing matching concepts",
        "values": [
          {
            "value": "SNOMED",
            "display_name": "SNOMED CT",
            "count": 847,
            "percentage": 67.9,
            "description": "Systematized Nomenclature of Medicine Clinical Terms",
            "metadata": {
              "organization": "SNOMED International",
              "version": "2024.2",
              "update_frequency": "Bi-annual",
              "coverage_domains": [
                "Condition",
                "Procedure", 
                "Observation"
              ]
            },
            "trend_info": {
              "trend": "stable",
              "recent_additions": 23
            }
          },
          {
            "value": "ICD10CM",
            "display_name": "ICD-10-CM",
            "count": 234,
            "percentage": 18.8,
            "description": "International Classification of Diseases, 10th Revision, Clinical Modification",
            "metadata": {
              "organization": "WHO/CDC",
              "version": "2024",
              "update_frequency": "Annual",
              "coverage_domains": [
                "Condition"
              ]
            },
            "trend_info": {
              "trend": "stable",
              "recent_additions": 5
            }
          },
          {
            "value": "LOINC",
            "display_name": "LOINC",
            "count": 89,
            "percentage": 7.1,
            "description": "Logical Observation Identifiers Names and Codes",
            "metadata": {
              "organization": "LOINC Committee",
              "version": "2.76",
              "update_frequency": "Bi-annual",
              "coverage_domains": [
                "Measurement",
                "Observation"
              ]
            },
            "trend_info": {
              "trend": "growing",
              "recent_additions": 12
            }
          },
          {
            "value": "RXNORM",
            "display_name": "RxNorm",
            "count": 77,
            "percentage": 6.2,
            "description": "Normalized names for clinical drugs",
            "metadata": {
              "organization": "NLM",
              "version": "2024-01",
              "update_frequency": "Monthly",
              "coverage_domains": [
                "Drug"
              ]
            },
            "trend_info": {
              "trend": "stable",
              "recent_additions": 8
            }
          }
        ]
      },
      "domain": {
        "facet_type": "domain",
        "display_name": "Medical Domains",
        "values": [
          {
            "value": "Condition",
            "display_name": "Condition",
            "count": 923,
            "percentage": 74.0,
            "description": "Clinical conditions, diseases, and disorders",
            "clinical_context": "Diagnostic and clinical conditions",
            "specialties": [
              "endocrinology",
              "internal_medicine",
              "family_medicine"
            ],
            "subcategories": [
              "Metabolic disorders",
              "Endocrine disorders",
              "Chronic conditions"
            ]
          },
          {
            "value": "Observation",
            "display_name": "Observation",
            "count": 156,
            "percentage": 12.5,
            "description": "Clinical observations and findings",
            "clinical_context": "Clinical assessments and observations",
            "specialties": [
              "endocrinology",
              "laboratory_medicine"
            ],
            "subcategories": [
              "Laboratory findings",
              "Clinical assessments"
            ]
          },
          {
            "value": "Measurement",
            "display_name": "Measurement",
            "count": 89,
            "percentage": 7.1,
            "description": "Quantitative measurements and test results",
            "clinical_context": "Laboratory tests and measurements",
            "specialties": [
              "laboratory_medicine",
              "endocrinology"
            ],
            "subcategories": [
              "Blood glucose tests",
              "HbA1c measurements"
            ]
          },
          {
            "value": "Drug",
            "display_name": "Drug", 
            "count": 79,
            "percentage": 6.3,
            "description": "Medications and pharmaceutical products",
            "clinical_context": "Diabetes medications and treatments",
            "specialties": [
              "endocrinology",
              "pharmacy"
            ],
            "subcategories": [
              "Antidiabetic agents",
              "Insulin preparations"
            ]
          }
        ]
      },
      "concept_class": {
        "facet_type": "concept_class",
        "display_name": "Concept Classes",
        "values": [
          {
            "value": "Clinical Finding",
            "display_name": "Clinical Finding",
            "count": 623,
            "percentage": 50.0,
            "description": "Clinical observations and findings",
            "vocabulary_distribution": [
              {"vocabulary": "SNOMED", "count": 598},
              {"vocabulary": "ICD10CM", "count": 25}
            ],
            "typical_use_cases": [
              "Diagnosis",
              "Clinical documentation",
              "Medical coding"
            ]
          },
          {
            "value": "Disorder",
            "display_name": "Disorder",
            "count": 234,
            "percentage": 18.8,
            "description": "Medical disorders and conditions",
            "vocabulary_distribution": [
              {"vocabulary": "SNOMED", "count": 187},
              {"vocabulary": "ICD10CM", "count": 47}
            ],
            "typical_use_cases": [
              "Disease classification",
              "Medical billing"
            ]
          },
          {
            "value": "3-char billing code",
            "display_name": "ICD-10-CM Category",
            "count": 156,
            "percentage": 12.5,
            "description": "ICD-10-CM 3-character category codes",
            "vocabulary_distribution": [
              {"vocabulary": "ICD10CM", "count": 156}
            ],
            "typical_use_cases": [
              "Medical billing",
              "Administrative coding"
            ]
          }
        ]
      },
      "specialty": {
        "facet_type": "specialty",
        "display_name": "Medical Specialties",
        "values": [
          {
            "value": "endocrinology",
            "display_name": "Endocrinology",
            "count": 1089,
            "relevance_score": 0.95,
            "primary_domains": [
              "Condition",
              "Observation",
              "Drug"
            ],
            "common_procedures": [
              "Blood glucose monitoring",
              "HbA1c testing",
              "Insulin therapy"
            ],
            "related_specialties": [
              "internal_medicine",
              "family_medicine"
            ]
          },
          {
            "value": "internal_medicine",
            "display_name": "Internal Medicine",
            "count": 923,
            "relevance_score": 0.87,
            "primary_domains": [
              "Condition",
              "Observation"
            ],
            "common_procedures": [
              "Diabetes management",
              "Medication management"
            ],
            "related_specialties": [
              "endocrinology",
              "family_medicine"
            ]
          },
          {
            "value": "family_medicine",
            "display_name": "Family Medicine",
            "count": 756,
            "relevance_score": 0.78,
            "primary_domains": [
              "Condition",
              "Observation"
            ],
            "common_procedures": [
              "Diabetes screening",
              "Patient education"
            ],
            "related_specialties": [
              "internal_medicine",
              "endocrinology"
            ]
          },
          {
            "value": "ophthalmology",
            "display_name": "Ophthalmology",
            "count": 234,
            "relevance_score": 0.65,
            "primary_domains": [
              "Condition",
              "Procedure"
            ],
            "common_procedures": [
              "Diabetic retinopathy screening",
              "Retinal examination"
            ],
            "related_specialties": [
              "endocrinology"
            ]
          }
        ]
      }
    },
    "facet_relationships": {
      "correlations": [
        {
          "facet_types": ["domain", "specialty"],
          "correlation": "Condition domain strongly correlates with endocrinology specialty"
        }
      ],
      "hierarchies": [
        {
          "parent": "Condition",
          "children": ["Clinical Finding", "Disorder"]
        }
      ],
      "exclusions": [
        {
          "facet_type": "standard_concept",
          "mutually_exclusive": ["S", "N"]
        }
      ]
    },
    "suggested_filters": [
      {
        "filter_name": "Endocrine Conditions",
        "filter_combination": {
          "domain": "Condition",
          "specialty": "endocrinology",
          "concept_class": "Clinical Finding"
        },
        "expected_results": 623,
        "use_case": "Clinical diabetes management"
      },
      {
        "filter_name": "Diabetes Medications",
        "filter_combination": {
          "domain": "Drug",
          "specialty": "endocrinology",
          "vocabulary": "RXNORM"
        },
        "expected_results": 77,
        "use_case": "Pharmaceutical diabetes treatment"
      }
    ]
  },
  "meta": {
    "request_id": "req_search_facets_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "facet_engine_version": "v2.3.1",
    "total_facet_values": 47,
    "computation_time_ms": 234,
    "cache_info": {
      "cached": true,
      "cache_key": "facets_diabetes_standard",
      "ttl_remaining": 3456
    },
    "vocab_release": "2025.2"
  }
}

curl -X GET "https://api.omophub.com/v1/search/facets?query=diabetes&facet_types=vocabulary,domain,concept_class,specialty&include_counts=true&include_percentages=true&max_facet_values=20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "query": "diabetes",
    "facet_metadata": {
      "total_concepts": 1247,
      "facet_types_included": [
        "vocabulary",
        "domain", 
        "concept_class",
        "specialty"
      ],
      "facet_depth": "standard",
      "generation_time_ms": 234,
      "context_applied": {
        "medical_context": null,
        "user_context": null,
        "temporal_scope": "current"
      }
    },
    "facets": {
      "vocabulary": {
        "facet_type": "vocabulary",
        "display_name": "Medical Vocabularies",
        "description": "Source vocabularies containing matching concepts",
        "values": [
          {
            "value": "SNOMED",
            "display_name": "SNOMED CT",
            "count": 847,
            "percentage": 67.9,
            "description": "Systematized Nomenclature of Medicine Clinical Terms",
            "metadata": {
              "organization": "SNOMED International",
              "version": "2024.2",
              "update_frequency": "Bi-annual",
              "coverage_domains": [
                "Condition",
                "Procedure", 
                "Observation"
              ]
            },
            "trend_info": {
              "trend": "stable",
              "recent_additions": 23
            }
          },
          {
            "value": "ICD10CM",
            "display_name": "ICD-10-CM",
            "count": 234,
            "percentage": 18.8,
            "description": "International Classification of Diseases, 10th Revision, Clinical Modification",
            "metadata": {
              "organization": "WHO/CDC",
              "version": "2024",
              "update_frequency": "Annual",
              "coverage_domains": [
                "Condition"
              ]
            },
            "trend_info": {
              "trend": "stable",
              "recent_additions": 5
            }
          },
          {
            "value": "LOINC",
            "display_name": "LOINC",
            "count": 89,
            "percentage": 7.1,
            "description": "Logical Observation Identifiers Names and Codes",
            "metadata": {
              "organization": "LOINC Committee",
              "version": "2.76",
              "update_frequency": "Bi-annual",
              "coverage_domains": [
                "Measurement",
                "Observation"
              ]
            },
            "trend_info": {
              "trend": "growing",
              "recent_additions": 12
            }
          },
          {
            "value": "RXNORM",
            "display_name": "RxNorm",
            "count": 77,
            "percentage": 6.2,
            "description": "Normalized names for clinical drugs",
            "metadata": {
              "organization": "NLM",
              "version": "2024-01",
              "update_frequency": "Monthly",
              "coverage_domains": [
                "Drug"
              ]
            },
            "trend_info": {
              "trend": "stable",
              "recent_additions": 8
            }
          }
        ]
      },
      "domain": {
        "facet_type": "domain",
        "display_name": "Medical Domains",
        "values": [
          {
            "value": "Condition",
            "display_name": "Condition",
            "count": 923,
            "percentage": 74.0,
            "description": "Clinical conditions, diseases, and disorders",
            "clinical_context": "Diagnostic and clinical conditions",
            "specialties": [
              "endocrinology",
              "internal_medicine",
              "family_medicine"
            ],
            "subcategories": [
              "Metabolic disorders",
              "Endocrine disorders",
              "Chronic conditions"
            ]
          },
          {
            "value": "Observation",
            "display_name": "Observation",
            "count": 156,
            "percentage": 12.5,
            "description": "Clinical observations and findings",
            "clinical_context": "Clinical assessments and observations",
            "specialties": [
              "endocrinology",
              "laboratory_medicine"
            ],
            "subcategories": [
              "Laboratory findings",
              "Clinical assessments"
            ]
          },
          {
            "value": "Measurement",
            "display_name": "Measurement",
            "count": 89,
            "percentage": 7.1,
            "description": "Quantitative measurements and test results",
            "clinical_context": "Laboratory tests and measurements",
            "specialties": [
              "laboratory_medicine",
              "endocrinology"
            ],
            "subcategories": [
              "Blood glucose tests",
              "HbA1c measurements"
            ]
          },
          {
            "value": "Drug",
            "display_name": "Drug", 
            "count": 79,
            "percentage": 6.3,
            "description": "Medications and pharmaceutical products",
            "clinical_context": "Diabetes medications and treatments",
            "specialties": [
              "endocrinology",
              "pharmacy"
            ],
            "subcategories": [
              "Antidiabetic agents",
              "Insulin preparations"
            ]
          }
        ]
      },
      "concept_class": {
        "facet_type": "concept_class",
        "display_name": "Concept Classes",
        "values": [
          {
            "value": "Clinical Finding",
            "display_name": "Clinical Finding",
            "count": 623,
            "percentage": 50.0,
            "description": "Clinical observations and findings",
            "vocabulary_distribution": [
              {"vocabulary": "SNOMED", "count": 598},
              {"vocabulary": "ICD10CM", "count": 25}
            ],
            "typical_use_cases": [
              "Diagnosis",
              "Clinical documentation",
              "Medical coding"
            ]
          },
          {
            "value": "Disorder",
            "display_name": "Disorder",
            "count": 234,
            "percentage": 18.8,
            "description": "Medical disorders and conditions",
            "vocabulary_distribution": [
              {"vocabulary": "SNOMED", "count": 187},
              {"vocabulary": "ICD10CM", "count": 47}
            ],
            "typical_use_cases": [
              "Disease classification",
              "Medical billing"
            ]
          },
          {
            "value": "3-char billing code",
            "display_name": "ICD-10-CM Category",
            "count": 156,
            "percentage": 12.5,
            "description": "ICD-10-CM 3-character category codes",
            "vocabulary_distribution": [
              {"vocabulary": "ICD10CM", "count": 156}
            ],
            "typical_use_cases": [
              "Medical billing",
              "Administrative coding"
            ]
          }
        ]
      },
      "specialty": {
        "facet_type": "specialty",
        "display_name": "Medical Specialties",
        "values": [
          {
            "value": "endocrinology",
            "display_name": "Endocrinology",
            "count": 1089,
            "relevance_score": 0.95,
            "primary_domains": [
              "Condition",
              "Observation",
              "Drug"
            ],
            "common_procedures": [
              "Blood glucose monitoring",
              "HbA1c testing",
              "Insulin therapy"
            ],
            "related_specialties": [
              "internal_medicine",
              "family_medicine"
            ]
          },
          {
            "value": "internal_medicine",
            "display_name": "Internal Medicine",
            "count": 923,
            "relevance_score": 0.87,
            "primary_domains": [
              "Condition",
              "Observation"
            ],
            "common_procedures": [
              "Diabetes management",
              "Medication management"
            ],
            "related_specialties": [
              "endocrinology",
              "family_medicine"
            ]
          },
          {
            "value": "family_medicine",
            "display_name": "Family Medicine",
            "count": 756,
            "relevance_score": 0.78,
            "primary_domains": [
              "Condition",
              "Observation"
            ],
            "common_procedures": [
              "Diabetes screening",
              "Patient education"
            ],
            "related_specialties": [
              "internal_medicine",
              "endocrinology"
            ]
          },
          {
            "value": "ophthalmology",
            "display_name": "Ophthalmology",
            "count": 234,
            "relevance_score": 0.65,
            "primary_domains": [
              "Condition",
              "Procedure"
            ],
            "common_procedures": [
              "Diabetic retinopathy screening",
              "Retinal examination"
            ],
            "related_specialties": [
              "endocrinology"
            ]
          }
        ]
      }
    },
    "facet_relationships": {
      "correlations": [
        {
          "facet_types": ["domain", "specialty"],
          "correlation": "Condition domain strongly correlates with endocrinology specialty"
        }
      ],
      "hierarchies": [
        {
          "parent": "Condition",
          "children": ["Clinical Finding", "Disorder"]
        }
      ],
      "exclusions": [
        {
          "facet_type": "standard_concept",
          "mutually_exclusive": ["S", "N"]
        }
      ]
    },
    "suggested_filters": [
      {
        "filter_name": "Endocrine Conditions",
        "filter_combination": {
          "domain": "Condition",
          "specialty": "endocrinology",
          "concept_class": "Clinical Finding"
        },
        "expected_results": 623,
        "use_case": "Clinical diabetes management"
      },
      {
        "filter_name": "Diabetes Medications",
        "filter_combination": {
          "domain": "Drug",
          "specialty": "endocrinology",
          "vocabulary": "RXNORM"
        },
        "expected_results": 77,
        "use_case": "Pharmaceutical diabetes treatment"
      }
    ]
  },
  "meta": {
    "request_id": "req_search_facets_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "facet_engine_version": "v2.3.1",
    "total_facet_values": 47,
    "computation_time_ms": 234,
    "cache_info": {
      "cached": true,
      "cache_key": "facets_diabetes_standard",
      "ttl_remaining": 3456
    },
    "vocab_release": "2025.2"
  }
}

Overview

This endpoint provides faceted search capabilities for medical terminology, returning structured filters and categories that can be used to refine search results. It enables users to explore medical vocabularies through multiple dimensions such as domains, vocabularies, concept classes, and other medical attributes.

Query Parameters

query

string

Base search query to generate facets for (optional for general facets)

vocabulary_ids

string

Target vocabularies for facet generation (comma-separated)
Examples: SNOMED, ICD10CM,LOINC, RXNORM,NDC

domains

string

Pre-filter facets to specific domains (comma-separated)
Examples: Condition,Procedure, Drug,Device

concept_classes

string

Pre-filter facets to specific concept classes (comma-separated)

facet_types

string

default:"all"

Types of facets to include (comma-separated)
Options: vocabulary, domain, concept_class, standard_concept, specialty, usage_frequency, date_range, language, all

include_counts

boolean

default:"true"

Include concept counts for each facet value

include_percentages

boolean

default:"false"

Include percentage distributions for facet values

include_trends

boolean

default:"false"

Include trend information for facet values

medical_context

string

Medical specialty context for facet relevance
Examples: cardiology, oncology, pediatrics, emergency_medicine

user_context

string

User type for facet customization
Options: physician, nurse, pharmacist, researcher, patient, student

facet_depth

string

default:"standard"

Depth of facet hierarchy to return
Options: minimal, standard, detailed, comprehensive

min_count

integer

default:"1"

Minimum concept count for facet values to be included

max_facet_values

integer

default:"50"

Maximum number of values per facet type (max 200)

sort_facets_by

string

default:"count"

Sort order for facet values
Options: count, alphabetical, relevance, frequency, recent_usage

include_hierarchical

boolean

default:"true"

Include hierarchical facet structures where applicable

Include facets for related concepts

temporal_scope

string

default:"current"

Temporal scope for facet generation
Options: current, historical, trending, recent, all_time

language

string

default:"en"

Language for facet labels and descriptions

regional_variant

string

Regional variant for terminology preferences
Examples: US, UK, AU, CA

standard_concept

string

Filter facets by standard concept status: S, N, C

include_invalid

boolean

default:"false"

Include facets for invalid/deprecated concepts

vocab_release

string

Specific vocabulary release version (defaults to latest)

Response

success

boolean

Indicates if the request was successful

data

object

Show Search Facets

query

string

Base search query (if provided)

facet_metadata

object

Show Facet Metadata

total_concepts

integer

Total concepts matching the base query

facet_types_included

array

Types of facets included in response

facet_depth

string

Depth level of facets returned

generation_time_ms

integer

Time taken to generate facets

context_applied

object

Context filters applied to facet generation

facets

object

Show Facet Categories

vocabulary

object

Show Vocabulary Facets

facet_type

string

Type identifier: “vocabulary”

display_name

string

Human-readable facet name

description

string

Description of this facet type

values

array

Show Vocabulary Value

value

string

Vocabulary identifier

display_name

string

Human-readable vocabulary name

count

integer

Number of concepts in this vocabulary

percentage

number

Percentage of total concepts (if include_percentages=true)

description

string

Brief description of the vocabulary

metadata

object

Show Vocabulary Metadata

organization

string

Maintaining organization

version

string

Current version

update_frequency

string

How often updated

coverage_domains

array

Primary domains covered

trend_info

object

Trend information (if include_trends=true)

domain

object

Show Domain Facets

facet_type

string

Type identifier: “domain”

display_name

string

Human-readable facet name

values

array

Show Domain Value

value

string

Domain identifier

display_name

string

Human-readable domain name

count

integer

Number of concepts in this domain

percentage

number

Percentage of total concepts

description

string

Description of the domain

clinical_context

string

Clinical context of this domain

specialties

array

Medical specialties using this domain

subcategories

array

Hierarchical subcategories (if include_hierarchical=true)

concept_class

object

Show Concept Class Facets

facet_type

string

Type identifier: “concept_class”

display_name

string

Human-readable facet name

values

array

Show Concept Class Value

value

string

Concept class identifier

display_name

string

Human-readable class name

count

integer

Number of concepts in this class

percentage

number

Percentage of total concepts

description

string

Description of the concept class

vocabulary_distribution

array

Distribution across vocabularies

typical_use_cases

array

Common use cases for this class

specialty

object

Show Medical Specialty Facets

facet_type

string

Type identifier: “specialty”

display_name

string

Human-readable facet name

values

array

Show Specialty Value

value

string

Medical specialty identifier

display_name

string

Human-readable specialty name

count

integer

Number of concepts relevant to this specialty

relevance_score

number

Relevance score for this specialty

primary_domains

array

Primary domains for this specialty

common_procedures

array

Common procedures in this specialty

Related medical specialties

usage_frequency

object

Show Usage Frequency Facets

facet_type

string

Type identifier: “usage_frequency”

display_name

string

Human-readable facet name

values

array

Show Frequency Range

value

string

Frequency range identifier

display_name

string

Human-readable frequency range

count

integer

Number of concepts in this frequency range

range_definition

object

Definition of the frequency range

typical_concepts

array

Example concepts in this range

standard_concept

object

Show Standard Concept Facets

facet_type

string

Type identifier: “standard_concept”

display_name

string

Human-readable facet name

values

array

Show Standard Concept Value

value

string

Standard concept indicator (S, N, C)

display_name

string

Human-readable description

count

integer

Number of concepts with this status

description

string

Explanation of this standard concept status

use_cases

array

Common use cases for this concept type

date_range

object

Show Date Range Facets

facet_type

string

Type identifier: “date_range”

display_name

string

Human-readable facet name

values

array

Show Date Range Value

value

string

Date range identifier

display_name

string

Human-readable date range

count

integer

Number of concepts in this date range

start_date

string

Start date of the range

end_date

string

End date of the range

notable_changes

array

Notable changes in this time period

language

object

Show Language Facets

facet_type

string

Type identifier: “language”

display_name

string

Human-readable facet name

values

array

Show Language Value

value

string

Language code (ISO 639-1)

display_name

string

Human-readable language name

count

integer

Number of concepts with terms in this language

coverage_percentage

number

Percentage coverage in this language

translation_quality

string

Overall translation quality

regional_variants

array

Regional language variants available

facet_relationships

object

Show Facet Relationships

correlations

array

Correlations between different facet types

hierarchies

array

Hierarchical relationships between facet values

exclusions

array

Mutually exclusive facet combinations

suggested_filters

array

Suggested filter combinations based on context

Show Suggested Filter

filter_name

string

Human-readable filter name

filter_combination

object

Facet values to combine for this filter

expected_results

integer

Expected number of results with this filter

use_case

string

Typical use case for this filter combination

facet_engine_version

string

Facet generation engine version

total_facet_values

integer

Total number of facet values returned

computation_time_ms

integer

Time taken for facet computation

cache_info

object

Caching information for facets

meta

object

Show Metadata

request_id

string

Unique identifier for the request

timestamp

string

Request timestamp

vocab_release

string

Vocabulary release version used

curl -X GET "https://api.omophub.com/v1/search/facets?query=diabetes&facet_types=vocabulary,domain,concept_class,specialty&include_counts=true&include_percentages=true&max_facet_values=20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "query": "diabetes",
    "facet_metadata": {
      "total_concepts": 1247,
      "facet_types_included": [
        "vocabulary",
        "domain", 
        "concept_class",
        "specialty"
      ],
      "facet_depth": "standard",
      "generation_time_ms": 234,
      "context_applied": {
        "medical_context": null,
        "user_context": null,
        "temporal_scope": "current"
      }
    },
    "facets": {
      "vocabulary": {
        "facet_type": "vocabulary",
        "display_name": "Medical Vocabularies",
        "description": "Source vocabularies containing matching concepts",
        "values": [
          {
            "value": "SNOMED",
            "display_name": "SNOMED CT",
            "count": 847,
            "percentage": 67.9,
            "description": "Systematized Nomenclature of Medicine Clinical Terms",
            "metadata": {
              "organization": "SNOMED International",
              "version": "2024.2",
              "update_frequency": "Bi-annual",
              "coverage_domains": [
                "Condition",
                "Procedure", 
                "Observation"
              ]
            },
            "trend_info": {
              "trend": "stable",
              "recent_additions": 23
            }
          },
          {
            "value": "ICD10CM",
            "display_name": "ICD-10-CM",
            "count": 234,
            "percentage": 18.8,
            "description": "International Classification of Diseases, 10th Revision, Clinical Modification",
            "metadata": {
              "organization": "WHO/CDC",
              "version": "2024",
              "update_frequency": "Annual",
              "coverage_domains": [
                "Condition"
              ]
            },
            "trend_info": {
              "trend": "stable",
              "recent_additions": 5
            }
          },
          {
            "value": "LOINC",
            "display_name": "LOINC",
            "count": 89,
            "percentage": 7.1,
            "description": "Logical Observation Identifiers Names and Codes",
            "metadata": {
              "organization": "LOINC Committee",
              "version": "2.76",
              "update_frequency": "Bi-annual",
              "coverage_domains": [
                "Measurement",
                "Observation"
              ]
            },
            "trend_info": {
              "trend": "growing",
              "recent_additions": 12
            }
          },
          {
            "value": "RXNORM",
            "display_name": "RxNorm",
            "count": 77,
            "percentage": 6.2,
            "description": "Normalized names for clinical drugs",
            "metadata": {
              "organization": "NLM",
              "version": "2024-01",
              "update_frequency": "Monthly",
              "coverage_domains": [
                "Drug"
              ]
            },
            "trend_info": {
              "trend": "stable",
              "recent_additions": 8
            }
          }
        ]
      },
      "domain": {
        "facet_type": "domain",
        "display_name": "Medical Domains",
        "values": [
          {
            "value": "Condition",
            "display_name": "Condition",
            "count": 923,
            "percentage": 74.0,
            "description": "Clinical conditions, diseases, and disorders",
            "clinical_context": "Diagnostic and clinical conditions",
            "specialties": [
              "endocrinology",
              "internal_medicine",
              "family_medicine"
            ],
            "subcategories": [
              "Metabolic disorders",
              "Endocrine disorders",
              "Chronic conditions"
            ]
          },
          {
            "value": "Observation",
            "display_name": "Observation",
            "count": 156,
            "percentage": 12.5,
            "description": "Clinical observations and findings",
            "clinical_context": "Clinical assessments and observations",
            "specialties": [
              "endocrinology",
              "laboratory_medicine"
            ],
            "subcategories": [
              "Laboratory findings",
              "Clinical assessments"
            ]
          },
          {
            "value": "Measurement",
            "display_name": "Measurement",
            "count": 89,
            "percentage": 7.1,
            "description": "Quantitative measurements and test results",
            "clinical_context": "Laboratory tests and measurements",
            "specialties": [
              "laboratory_medicine",
              "endocrinology"
            ],
            "subcategories": [
              "Blood glucose tests",
              "HbA1c measurements"
            ]
          },
          {
            "value": "Drug",
            "display_name": "Drug", 
            "count": 79,
            "percentage": 6.3,
            "description": "Medications and pharmaceutical products",
            "clinical_context": "Diabetes medications and treatments",
            "specialties": [
              "endocrinology",
              "pharmacy"
            ],
            "subcategories": [
              "Antidiabetic agents",
              "Insulin preparations"
            ]
          }
        ]
      },
      "concept_class": {
        "facet_type": "concept_class",
        "display_name": "Concept Classes",
        "values": [
          {
            "value": "Clinical Finding",
            "display_name": "Clinical Finding",
            "count": 623,
            "percentage": 50.0,
            "description": "Clinical observations and findings",
            "vocabulary_distribution": [
              {"vocabulary": "SNOMED", "count": 598},
              {"vocabulary": "ICD10CM", "count": 25}
            ],
            "typical_use_cases": [
              "Diagnosis",
              "Clinical documentation",
              "Medical coding"
            ]
          },
          {
            "value": "Disorder",
            "display_name": "Disorder",
            "count": 234,
            "percentage": 18.8,
            "description": "Medical disorders and conditions",
            "vocabulary_distribution": [
              {"vocabulary": "SNOMED", "count": 187},
              {"vocabulary": "ICD10CM", "count": 47}
            ],
            "typical_use_cases": [
              "Disease classification",
              "Medical billing"
            ]
          },
          {
            "value": "3-char billing code",
            "display_name": "ICD-10-CM Category",
            "count": 156,
            "percentage": 12.5,
            "description": "ICD-10-CM 3-character category codes",
            "vocabulary_distribution": [
              {"vocabulary": "ICD10CM", "count": 156}
            ],
            "typical_use_cases": [
              "Medical billing",
              "Administrative coding"
            ]
          }
        ]
      },
      "specialty": {
        "facet_type": "specialty",
        "display_name": "Medical Specialties",
        "values": [
          {
            "value": "endocrinology",
            "display_name": "Endocrinology",
            "count": 1089,
            "relevance_score": 0.95,
            "primary_domains": [
              "Condition",
              "Observation",
              "Drug"
            ],
            "common_procedures": [
              "Blood glucose monitoring",
              "HbA1c testing",
              "Insulin therapy"
            ],
            "related_specialties": [
              "internal_medicine",
              "family_medicine"
            ]
          },
          {
            "value": "internal_medicine",
            "display_name": "Internal Medicine",
            "count": 923,
            "relevance_score": 0.87,
            "primary_domains": [
              "Condition",
              "Observation"
            ],
            "common_procedures": [
              "Diabetes management",
              "Medication management"
            ],
            "related_specialties": [
              "endocrinology",
              "family_medicine"
            ]
          },
          {
            "value": "family_medicine",
            "display_name": "Family Medicine",
            "count": 756,
            "relevance_score": 0.78,
            "primary_domains": [
              "Condition",
              "Observation"
            ],
            "common_procedures": [
              "Diabetes screening",
              "Patient education"
            ],
            "related_specialties": [
              "internal_medicine",
              "endocrinology"
            ]
          },
          {
            "value": "ophthalmology",
            "display_name": "Ophthalmology",
            "count": 234,
            "relevance_score": 0.65,
            "primary_domains": [
              "Condition",
              "Procedure"
            ],
            "common_procedures": [
              "Diabetic retinopathy screening",
              "Retinal examination"
            ],
            "related_specialties": [
              "endocrinology"
            ]
          }
        ]
      }
    },
    "facet_relationships": {
      "correlations": [
        {
          "facet_types": ["domain", "specialty"],
          "correlation": "Condition domain strongly correlates with endocrinology specialty"
        }
      ],
      "hierarchies": [
        {
          "parent": "Condition",
          "children": ["Clinical Finding", "Disorder"]
        }
      ],
      "exclusions": [
        {
          "facet_type": "standard_concept",
          "mutually_exclusive": ["S", "N"]
        }
      ]
    },
    "suggested_filters": [
      {
        "filter_name": "Endocrine Conditions",
        "filter_combination": {
          "domain": "Condition",
          "specialty": "endocrinology",
          "concept_class": "Clinical Finding"
        },
        "expected_results": 623,
        "use_case": "Clinical diabetes management"
      },
      {
        "filter_name": "Diabetes Medications",
        "filter_combination": {
          "domain": "Drug",
          "specialty": "endocrinology",
          "vocabulary": "RXNORM"
        },
        "expected_results": 77,
        "use_case": "Pharmaceutical diabetes treatment"
      }
    ]
  },
  "meta": {
    "request_id": "req_search_facets_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "facet_engine_version": "v2.3.1",
    "total_facet_values": 47,
    "computation_time_ms": 234,
    "cache_info": {
      "cached": true,
      "cache_key": "facets_diabetes_standard",
      "ttl_remaining": 3456
    },
    "vocab_release": "2025.2"
  }
}

Usage Examples

Get facets for a specific search query:

curl -X GET "https://api.omophub.com/v1/search/facets?query=pneumonia&facet_types=vocabulary,domain,concept_class&include_counts=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get detailed facets with all information:

curl -X GET "https://api.omophub.com/v1/search/facets?query=cardiac&facet_types=all&include_counts=true&include_percentages=true&include_trends=true&facet_depth=comprehensive" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get facets relevant to a specific medical specialty:

curl -X GET "https://api.omophub.com/v1/search/facets?medical_context=cardiology&user_context=physician&facet_types=domain,concept_class,specialty&include_hierarchical=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get facets for specific vocabularies:

curl -X GET "https://api.omophub.com/v1/search/facets?vocabulary_ids=SNOMED,ICD10CM&facet_types=domain,concept_class,usage_frequency&min_count=10&max_facet_values=15" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get facets for general terminology navigation:

curl -X GET "https://api.omophub.com/v1/search/facets?facet_types=vocabulary,domain,specialty&sort_facets_by=count&include_related_facets=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

User-Contextualized Facets

Get facets customized for specific user types:

curl -X GET "https://api.omophub.com/v1/search/facets?query=medication&user_context=pharmacist&facet_types=vocabulary,domain,concept_class&medical_context=pharmacy" \
  -H "Authorization: Bearer YOUR_API_KEY"

Purpose: Filter by source vocabulary
Use Cases: Compare terminology coverage, choose appropriate vocabulary
Values: SNOMED, ICD10CM, LOINC, RxNorm, HCPCS, HCPCS
Metadata: Organization, version, update frequency, coverage

Domain Facets

Purpose: Filter by medical domain
Use Cases: Focus on specific types of medical concepts
Values: Condition, Procedure, Drug, Device, Measurement, Observation
Hierarchy: Sub-domains and categories within each domain

Purpose: Filter by concept classification
Use Cases: Refine search to specific concept types
Values: Clinical Finding, Procedure, Pharmaceutical Product, etc.
Context: Vocabulary-specific concept classes

Purpose: Filter by medical specialty relevance
Use Cases: Find concepts relevant to specific medical practices
Values: Cardiology, Oncology, Pediatrics, Emergency Medicine, etc.
Relationships: Related specialties and common procedures

Purpose: Filter by how commonly concepts are used
Use Cases: Find popular terms, discover rare conditions
Values: Very High, High, Medium, Low, Rare
Metrics: Search volume, clinical usage, documentation frequency

Purpose: Filter by OMOP standard concept status
Use Cases: Find standard concepts for analytics, non-standard for mapping
Values: Standard (S), Non-standard (N), Classification (C)
Usage: Critical for OMOP CDM implementations

Purpose: Filter by concept validity or update dates
Use Cases: Find recently updated concepts, historical analysis
Values: Current year, Last 5 years, Historical, etc.
Context: Version tracking and temporal analysis

Purpose: Filter by language availability
Use Cases: Multi-lingual implementations, translation coverage
Values: English, Spanish, French, German, etc.
Quality: Translation quality and coverage metrics

Minimal

Content: Basic facet values with counts
Performance: Fastest response time
Use Case: Simple filtering interfaces
Data: Value, count, basic display information

Standard

Content: Facet values with metadata and descriptions
Performance: Good response time
Use Case: General search interfaces
Data: Descriptions, percentages, basic relationships

Detailed

Content: Extended metadata and hierarchical relationships
Performance: Moderate response time
Use Case: Advanced search and analysis
Data: Hierarchies, correlations, trend information

Comprehensive

Content: Complete facet information with all metadata
Performance: Slower response time
Use Case: Research and comprehensive analysis
Data: All available metadata, relationships, and insights

User Context Customization

Physician Context

Priority: Clinical relevance, diagnostic focus
Emphasized Facets: Specialty, concept class, standard concepts
Hidden Facets: Patient-facing terminology, administrative codes
Sorting: Clinical relevance and frequency

Nurse Context

Priority: Patient care, nursing procedures
Emphasized Facets: Procedure domain, nursing specialties
Hidden Facets: Highly technical research terms
Sorting: Clinical usage and care relevance

Pharmacist Context

Priority: Drug-related terminology, pharmaceutical focus
Emphasized Facets: Drug domain, pharmaceutical vocabularies
Hidden Facets: Surgical procedures, diagnostic imaging
Sorting: Pharmaceutical relevance and usage

Researcher Context

Priority: Comprehensive coverage, analytical focus
Emphasized Facets: All vocabularies, comprehensive metadata
Hidden Facets: None (comprehensive view)
Sorting: Completeness and analytical value

Patient Context

Priority: Patient-friendly terminology, educational value
Emphasized Facets: Common conditions, patient-facing terms
Hidden Facets: Technical medical jargon, administrative codes
Sorting: Common usage and understandability

Student Context

Priority: Educational value, learning focus
Emphasized Facets: Concept classes, educational metadata
Hidden Facets: Highly specialized professional terms
Sorting: Educational relevance and frequency

Performance Optimization

Caching Strategies

Query-Based Cache: Cache facets for common queries
Context Cache: Cache facets for user contexts
Vocabulary Cache: Cache vocabulary-specific facets
Time-Based Cache: Cache with appropriate TTL

Computation Optimization

Pre-computed Facets: Common facet combinations
Incremental Updates: Update facets as data changes
Parallel Processing: Generate facets in parallel
Smart Filtering: Apply filters during facet generation

Response Optimization

Selective Loading: Load only requested facet types
Hierarchical Loading: Load parent facets first, children on demand
Compression: Compress large facet responses
Streaming: Stream large facet sets

Basic Search - Apply facet filters to search
Advanced Search - Complex search with multiple facets
Search Concepts - Search with facet filtering
List Domains - Detailed domain information

⌘I

API Reference

Concepts

Concept Hierarchy

Search

Search (Coming Soon)

Relationships

Domains & Classifications

Mappings

Vocabularies

​Overview

​Query Parameters

​Response

​Usage Examples

​Basic Facets for Query

​Comprehensive Facet Analysis

​Medical Specialty Focused Facets

​Vocabulary-Specific Facets

​General Navigation Facets

​User-Contextualized Facets

​Facet Types

​Vocabulary Facets

​Domain Facets

​Concept Class Facets

​Specialty Facets

​Usage Frequency Facets

​Standard Concept Facets

​Date Range Facets

​Language Facets

​Facet Depth Levels

​Minimal

​Standard

​Detailed

​Comprehensive

​User Context Customization

​Physician Context

​Nurse Context

​Pharmacist Context

​Researcher Context

​Patient Context

​Student Context

​Performance Optimization

​Caching Strategies

​Computation Optimization

​Response Optimization

​Related Endpoints

Overview

Query Parameters

Response

Usage Examples

Basic Facets for Query

Comprehensive Facet Analysis

Medical Specialty Focused Facets

Vocabulary-Specific Facets

General Navigation Facets

User-Contextualized Facets

Facet Types

Vocabulary Facets

Domain Facets

Concept Class Facets

Specialty Facets

Usage Frequency Facets

Standard Concept Facets

Date Range Facets

Language Facets

Facet Depth Levels

Minimal

Standard

Detailed

Comprehensive

User Context Customization

Physician Context

Nurse Context

Pharmacist Context

Researcher Context

Patient Context

Student Context

Performance Optimization

Caching Strategies

Computation Optimization

Response Optimization

Related Endpoints