> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Facets

> Retrieve search facets for filtering medical terminology search results by vocabulary, domain, concept class, and standard concept status.

## 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

<ParamField query="query" type="string">
  Search query to generate facets for. When provided, facets reflect the distribution of matching concepts.
</ParamField>

<ParamField query="vocabulary_ids" type="string">
  Filter facets to specific vocabularies (comma-separated)

  <br />

  **Examples**: `SNOMED`, `ICD10CM,LOINC`, `RXNORM`
</ParamField>

<ParamField query="vocab_release" type="string">
  Specific vocabulary release version (defaults to latest)

  <br />

  **Examples**: `2025.1`, `2024.2`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  Contains the faceted search results

  <Expandable title="data">
    <ResponseField name="query" type="string">
      The search query provided (empty string if none)
    </ResponseField>

    <ResponseField name="facets" type="object">
      Object containing facet categories and their values

      <Expandable title="facets">
        <ResponseField name="vocabularies" type="array">
          Vocabulary facets with concept counts

          <Expandable title="vocabulary item">
            <ResponseField name="vocabulary_id" type="string">
              Vocabulary identifier (e.g., "SNOMED", "ICD10CM")
            </ResponseField>

            <ResponseField name="count" type="integer">
              Number of concepts in this vocabulary matching the query
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="domains" type="array">
          Domain facets with concept counts

          <Expandable title="domain item">
            <ResponseField name="domain_id" type="string">
              Domain identifier (e.g., "Condition", "Drug", "Procedure")
            </ResponseField>

            <ResponseField name="count" type="integer">
              Number of concepts in this domain matching the query
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="concept_classes" type="array">
          Concept class facets with counts

          <Expandable title="concept_class item">
            <ResponseField name="concept_class_id" type="string">
              Concept class identifier (e.g., "Clinical Finding", "Procedure")
            </ResponseField>

            <ResponseField name="count" type="integer">
              Number of concepts in this class matching the query
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="standard_concepts" type="array">
          Standard concept status facets

          <Expandable title="standard_concept item">
            <ResponseField name="standard_concept" type="string">
              Standard concept indicator: `S` (Standard), `C` (Classification), `N` (Non-standard)
            </ResponseField>

            <ResponseField name="count" type="integer">
              Number of concepts with this status matching the query
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Response metadata

  <Expandable title="meta">
    <ResponseField name="request_id" type="string">
      Unique identifier for the request
    </ResponseField>

    <ResponseField name="vocab_release" type="string">
      Vocabulary release version used
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.omophub.com/v1/search/facets?query=diabetes&vocabulary_ids=SNOMED,ICD10CM" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.omophub.com/v1/search/facets?query=diabetes&vocabulary_ids=SNOMED,ICD10CM',
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.omophub.com/v1/search/facets",
      params={
          "query": "diabetes",
          "vocabulary_ids": "SNOMED,ICD10CM"
      },
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

## Usage Examples

### Get Facets for a Search Query

```bash theme={null}
GET /v1/search/facets?query=hypertension
```

### Filter Facets by Vocabulary

```bash theme={null}
GET /v1/search/facets?query=medication&vocabulary_ids=RXNORM,NDC
```

### General Facets Without Query

Get overall distribution of concepts:

```bash theme={null}
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

## Related Endpoints

* [Basic Search](/api-reference/search/basic-search) - Apply facet filters to search
* [Advanced Search](/api-reference/search/advanced-search) - Complex search with multiple filters