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

# Get Concept Hierarchy

> Retrieve the complete OMOP hierarchy for a concept - ancestors and descendants in one unified view for phenotype development and concept sets.

This endpoint provides a comprehensive hierarchical view of a concept, showing its position within the medical vocabulary structure by including both ancestor (parent) and descendant (child) relationships in a single response.

## Path Parameters

<ParamField path="concept_id" type="integer" required>
  The unique identifier of the concept to retrieve hierarchy for

  <br />

  **Example:** `73211009` (Diabetes mellitus)
</ParamField>

## Query Parameters

<ParamField query="format" type="string" optional default="flat">
  Response format for hierarchy data

  <br />

  **Options:** `flat`, `graph`

  <br />

  * `flat`: Returns ancestors and descendants as separate arrays (default)
  * `graph`: Returns nodes and edges for visualization (similar to OHDSI Athena)
</ParamField>

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

  <br />

  **Example:** `SNOMED,ICD10CM`
</ParamField>

<ParamField query="domain_ids" type="string" optional>
  Filter hierarchy to specific domains (comma-separated)

  <br />

  **Example:** `Condition,Drug`
</ParamField>

<ParamField query="max_levels" type="integer" optional default="10">
  Maximum number of hierarchy levels to traverse in both directions

  <br />

  **Range:** `1-20`
</ParamField>

<ParamField query="max_results" type="integer" optional default="500">
  Maximum number of results to return per direction (ancestors/descendants) for performance optimization

  <br />

  **Range:** `1-5000`

  <br />

  **Recommended:** Use 100-500 for interactive queries, up to 1000 for bulk analysis
</ParamField>

<ParamField query="relationship_types" type="string" optional default="Is a">
  Comma-separated list of relationship types to follow for hierarchy traversal

  <br />

  **Example:** `Is a,Part of`
</ParamField>

<ParamField query="include_invalid" type="boolean" optional default="true">
  Include deprecated/invalid concepts in hierarchy
</ParamField>

<ParamField query="vocab_release" type="string" optional>
  Specific vocabulary release version to query

  <br />

  **Example:** `2025.1`
</ParamField>

## Response

### Flat Format (default)

<ResponseField name="concept_id" type="integer">
  The concept ID for which hierarchy was retrieved
</ResponseField>

<ResponseField name="ancestors" type="array">
  Array of ancestor concepts in hierarchical order

  <Expandable title="Ancestor Concept Object">
    <ResponseField name="concept_id" type="integer">
      Unique identifier for the ancestor concept
    </ResponseField>

    <ResponseField name="concept_name" type="string">
      Standard name of the ancestor concept
    </ResponseField>

    <ResponseField name="concept_code" type="string">
      Original code from the vocabulary
    </ResponseField>

    <ResponseField name="vocabulary_id" type="string">
      Vocabulary containing this ancestor
    </ResponseField>

    <ResponseField name="vocabulary_name" type="string">
      Human-readable vocabulary name
    </ResponseField>

    <ResponseField name="domain_id" type="string">
      Domain classification
    </ResponseField>

    <ResponseField name="concept_class_id" type="string">
      Concept class identifier
    </ResponseField>

    <ResponseField name="standard_concept" type="string">
      Standard concept designation ('S', 'C', or null)
    </ResponseField>

    <ResponseField name="level" type="integer">
      Distance from source concept
    </ResponseField>

    <ResponseField name="min_levels_of_separation" type="integer">
      Minimum levels of separation from source concept
    </ResponseField>

    <ResponseField name="max_levels_of_separation" type="integer">
      Maximum levels of separation from source concept
    </ResponseField>

    <ResponseField name="relationship_id" type="string">
      Relationship type ID (e.g., "Is a")
    </ResponseField>

    <ResponseField name="relationship_name" type="string">
      Relationship type name
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="descendants" type="array">
  Array of descendant concepts in hierarchical order

  <Expandable title="Descendant Concept Object">
    <ResponseField name="concept_id" type="integer">
      Unique identifier for the descendant concept
    </ResponseField>

    <ResponseField name="concept_name" type="string">
      Standard name of the descendant concept
    </ResponseField>

    <ResponseField name="concept_code" type="string">
      Original code from the vocabulary
    </ResponseField>

    <ResponseField name="vocabulary_id" type="string">
      Vocabulary containing this descendant
    </ResponseField>

    <ResponseField name="vocabulary_name" type="string">
      Human-readable vocabulary name
    </ResponseField>

    <ResponseField name="domain_id" type="string">
      Domain classification
    </ResponseField>

    <ResponseField name="concept_class_id" type="string">
      Concept class identifier
    </ResponseField>

    <ResponseField name="standard_concept" type="string">
      Standard concept designation ('S', 'C', or null)
    </ResponseField>

    <ResponseField name="level" type="integer">
      Distance from source concept
    </ResponseField>

    <ResponseField name="min_levels_of_separation" type="integer">
      Minimum levels of separation from source concept
    </ResponseField>

    <ResponseField name="max_levels_of_separation" type="integer">
      Maximum levels of separation from source concept
    </ResponseField>

    <ResponseField name="relationship_id" type="string">
      Relationship type ID (e.g., "Subsumes")
    </ResponseField>

    <ResponseField name="relationship_name" type="string">
      Relationship type name
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="level" type="integer">
  Current concept's level in the hierarchy
</ResponseField>

<ResponseField name="max_level" type="integer">
  Maximum hierarchy depth
</ResponseField>

<ResponseField name="total_ancestors" type="integer">
  Total number of ancestor concepts
</ResponseField>

<ResponseField name="total_descendants" type="integer">
  Total number of descendant concepts
</ResponseField>

### Graph Format (format=graph)

<ResponseField name="concept_id" type="integer">
  The concept ID for which hierarchy was retrieved
</ResponseField>

<ResponseField name="nodes" type="array">
  Array of concept nodes for visualization

  <Expandable title="Node Object">
    <ResponseField name="id" type="integer">
      Unique identifier for the concept
    </ResponseField>

    <ResponseField name="name" type="string">
      Concept name
    </ResponseField>

    <ResponseField name="level" type="integer">
      Hierarchical level (0 for central concept, negative for ancestors, positive for descendants)
    </ResponseField>

    <ResponseField name="vocabulary_id" type="string">
      Vocabulary containing this concept
    </ResponseField>

    <ResponseField name="domain_id" type="string">
      Domain classification
    </ResponseField>

    <ResponseField name="concept_class_id" type="string">
      Concept class identifier
    </ResponseField>

    <ResponseField name="standard_concept" type="string">
      Standard concept designation ('S', 'C', or null)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="edges" type="array">
  Array of relationship edges between concepts

  <Expandable title="Edge Object">
    <ResponseField name="from" type="integer">
      Source concept ID
    </ResponseField>

    <ResponseField name="to" type="integer">
      Target concept ID
    </ResponseField>

    <ResponseField name="relationship_id" type="string">
      Relationship type (e.g., "Is a", "Subsumes")
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL (flat format) theme={null}
  curl -X GET "https://api.omophub.com/v1/concepts/73211009/hierarchy?max_levels=3" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (graph format) theme={null}
  curl -X GET "https://api.omophub.com/v1/concepts/73211009/hierarchy?format=graph&max_levels=3" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python (flat format) theme={null}
  import requests

  concept_id = 73211009  # Diabetes mellitus
  url = f"https://api.omophub.com/v1/concepts/{concept_id}/hierarchy"
  params = {
      "max_levels": 3,
      "vocabulary_ids": "SNOMED"
  }

  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  response = requests.get(url, params=params, headers=headers)
  hierarchy_data = response.json()

  print(f"Concept ID: {hierarchy_data['data']['concept_id']}")
  print(f"Total ancestors: {hierarchy_data['data']['total_ancestors']}")
  print(f"Total descendants: {hierarchy_data['data']['total_descendants']}")
  ```

  ```python Python (graph format for visualization) theme={null}
  import requests

  concept_id = 73211009
  url = f"https://api.omophub.com/v1/concepts/{concept_id}/hierarchy"
  params = {
      "format": "graph",
      "max_levels": 3
  }

  headers = {"Authorization": "Bearer YOUR_API_KEY"}

  response = requests.get(url, params=params, headers=headers)
  graph_data = response.json()

  # Use for D3.js or other visualization libraries
  nodes = graph_data['data']['nodes']
  edges = graph_data['data']['edges']
  print(f"Nodes: {len(nodes)}, Edges: {len(edges)}")
  ```

  ```javascript JavaScript (flat format) theme={null}
  const response = await fetch('https://api.omophub.com/v1/concepts/73211009/hierarchy?max_levels=3', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const hierarchyData = await response.json();
  console.log(`Ancestors: ${hierarchyData.data.total_ancestors}`);
  console.log(`Descendants: ${hierarchyData.data.total_descendants}`);
  ```

  ```javascript JavaScript (graph format) theme={null}
  const response = await fetch('https://api.omophub.com/v1/concepts/73211009/hierarchy?format=graph&max_levels=3', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const graphData = await response.json();
  // Use with D3.js force-directed graph
  const { nodes, edges } = graphData.data;
  ```
</RequestExample>

<ResponseExample>
  ```json Flat Format Response theme={null}
  {
    "success": true,
    "data": {
      "concept_id": 73211009,
      "ancestors": [
        {
          "concept_id": 362969004,
          "concept_name": "Disorder of endocrine system",
          "concept_code": "362969004",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "SNOMED Clinical Terms",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "level": 1,
          "min_levels_of_separation": 1,
          "max_levels_of_separation": 1,
          "relationship_id": "Is a",
          "relationship_name": "Is a"
        },
        {
          "concept_id": 64572001,
          "concept_name": "Disease",
          "concept_code": "64572001",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "SNOMED Clinical Terms",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "level": 2,
          "min_levels_of_separation": 2,
          "max_levels_of_separation": 2,
          "relationship_id": "Is a",
          "relationship_name": "Is a"
        }
      ],
      "descendants": [
        {
          "concept_id": 44054006,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "SNOMED Clinical Terms",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "level": 1,
          "min_levels_of_separation": 1,
          "max_levels_of_separation": 1,
          "relationship_id": "Subsumes",
          "relationship_name": "Subsumes"
        },
        {
          "concept_id": 46635009,
          "concept_name": "Type 1 diabetes mellitus",
          "concept_code": "46635009",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "SNOMED Clinical Terms",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "level": 1,
          "min_levels_of_separation": 1,
          "max_levels_of_separation": 1,
          "relationship_id": "Subsumes",
          "relationship_name": "Subsumes"
        }
      ],
      "level": 3,
      "max_level": 5,
      "total_ancestors": 2,
      "total_descendants": 2
    },
    "meta": {
      "request_id": "req_hierarchy_123",
      "timestamp": "2024-12-22T10:30:00Z",
      "vocab_release": "2025.2"
    }
  }
  ```

  ```json Graph Format Response theme={null}
  {
    "success": true,
    "data": {
      "concept_id": 73211009,
      "nodes": [
        {
          "id": 73211009,
          "name": "Diabetes mellitus",
          "level": 0,
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        {
          "id": 362969004,
          "name": "Disorder of endocrine system",
          "level": -1,
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        {
          "id": 44054006,
          "name": "Type 2 diabetes mellitus",
          "level": 1,
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        {
          "id": 46635009,
          "name": "Type 1 diabetes mellitus",
          "level": 1,
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        }
      ],
      "edges": [
        {
          "from": 73211009,
          "to": 362969004,
          "relationship_id": "Is a"
        },
        {
          "from": 73211009,
          "to": 44054006,
          "relationship_id": "Subsumes"
        },
        {
          "from": 73211009,
          "to": 46635009,
          "relationship_id": "Subsumes"
        }
      ]
    },
    "meta": {
      "request_id": "req_hierarchy_456",
      "timestamp": "2024-12-22T10:30:00Z",
      "vocab_release": "2025.2"
    }
  }
  ```
</ResponseExample>

## Usage Examples

### Basic Hierarchy View

Get complete hierarchy context for a concept:

```javascript theme={null}
const hierarchy = await fetch('/v1/concepts/73211009/hierarchy');
```

### Limited Depth Hierarchy

Control the depth of ancestor and descendant traversal:

```javascript theme={null}
const limitedHierarchy = await fetch('/v1/concepts/73211009/hierarchy?max_levels=2&max_results=100');
```

### Graph Format for Visualization

Get hierarchy in graph structure for D3.js or similar visualization libraries:

```javascript theme={null}
const graphData = await fetch('/v1/concepts/73211009/hierarchy?format=graph&max_levels=3');
```

### Filtered Hierarchy

Filter to specific vocabularies:

```javascript theme={null}
const filteredHierarchy = await fetch('/v1/concepts/73211009/hierarchy?vocabulary_ids=SNOMED&domain_ids=Condition');
```

## Related Endpoints

* [Get Concept Ancestors](/api-reference/hierarchy/get-concept-ancestors) - Detailed ancestor information with pagination
* [Get Concept Descendants](/api-reference/hierarchy/get-concept-descendants) - Detailed descendant information with pagination
* [Get Concept Relationships](/api-reference/relationships/get-concept-relationships) - All concept relationships
* [Search Concepts](/api-reference/search/basic-search) - Search within hierarchies

## Notes

* The hierarchy endpoint combines ancestors and descendants in a single request for convenience
* Use the `graph` format when building visualizations (compatible with D3.js, Cytoscape, etc.)
* The `flat` format is better for data processing and analysis
* In graph format, level 0 is the central concept, negative levels are ancestors, positive are descendants
* Large hierarchies may be limited by `max_results` to ensure performance
* Cross-vocabulary concepts may show relationships spanning multiple vocabularies