Skip to main content
curl -X GET "https://api.omophub.com/v1/search/facets?query=diabetes&vocabularies=SNOMED,ICD10CM" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "success": true,
  "data": {
    "query": "diabetes",
    "facets": {
      "vocabularies": [
        { "vocabulary_id": "SNOMED", "count": 245 },
        { "vocabulary_id": "ICD10CM", "count": 67 }
      ],
      "domains": [
        { "domain_id": "Condition", "count": 198 },
        { "domain_id": "Observation", "count": 87 },
        { "domain_id": "Drug", "count": 27 }
      ],
      "concept_classes": [
        { "concept_class_id": "Clinical Finding", "count": 156 },
        { "concept_class_id": "Disorder", "count": 87 },
        { "concept_class_id": "Procedure", "count": 42 }
      ],
      "standard_concepts": [
        { "standard_concept": "S", "count": 245 },
        { "standard_concept": "C", "count": 34 },
        { "standard_concept": "N", "count": 33 }
      ]
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "vocab_release": "2025.1"
  }
}

Overview

This endpoint provides faceted search capabilities for medical terminology, returning aggregated counts that can be used to filter and refine search results. Facets help users understand the distribution of concepts across different dimensions.

Query Parameters

query
string
Search query to generate facets for. When provided, facets reflect the distribution of matching concepts.
vocabularies
string
Filter facets to specific vocabularies (comma-separated)
Examples: SNOMED, ICD10CM,LOINC, RXNORM
vocab_release
string
Specific vocabulary release version (defaults to latest)
Examples: 2025.1, 2024.4

Response

success
boolean
Indicates if the request was successful
data
object
Contains the faceted search results
meta
object
Response metadata
curl -X GET "https://api.omophub.com/v1/search/facets?query=diabetes&vocabularies=SNOMED,ICD10CM" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "success": true,
  "data": {
    "query": "diabetes",
    "facets": {
      "vocabularies": [
        { "vocabulary_id": "SNOMED", "count": 245 },
        { "vocabulary_id": "ICD10CM", "count": 67 }
      ],
      "domains": [
        { "domain_id": "Condition", "count": 198 },
        { "domain_id": "Observation", "count": 87 },
        { "domain_id": "Drug", "count": 27 }
      ],
      "concept_classes": [
        { "concept_class_id": "Clinical Finding", "count": 156 },
        { "concept_class_id": "Disorder", "count": 87 },
        { "concept_class_id": "Procedure", "count": 42 }
      ],
      "standard_concepts": [
        { "standard_concept": "S", "count": 245 },
        { "standard_concept": "C", "count": 34 },
        { "standard_concept": "N", "count": 33 }
      ]
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "vocab_release": "2025.1"
  }
}

Usage Examples

Get Facets for a Search Query

GET /v1/search/facets?query=hypertension

Filter Facets by Vocabulary

GET /v1/search/facets?query=medication&vocabularies=RXNORM,NDC

General Facets Without Query

Get overall distribution of concepts:
GET /v1/search/facets

Facet Types

Vocabularies

Shows distribution across medical vocabularies (SNOMED, ICD10CM, LOINC, RxNorm, etc.). Use to filter searches to specific terminology systems.

Domains

Shows distribution across clinical domains (Condition, Drug, Procedure, Measurement, etc.). Use to focus on specific types of medical concepts.

Concept Classes

Shows distribution across concept classifications (Clinical Finding, Disorder, Ingredient, etc.). Provides more granular filtering than domains.

Standard Concepts

Shows distribution by OMOP standard concept status:
  • S (Standard): Preferred concepts for OMOP CDM analytics
  • C (Classification): Classification concepts for grouping
  • N (Non-standard): Source concepts that map to standard concepts