Skip to main content
curl -X GET "https://api.omophub.com/v1/concepts/73211009/descendants?include_distance=true&max_levels=3" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "concept_id": 73211009,
    "concept_name": "Diabetes mellitus",
    "vocabulary_id": "SNOMED",
    "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",
        "hierarchy_level": 1,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "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",
        "hierarchy_level": 1,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "concept_id": 237599002,
        "concept_name": "Insulin dependent diabetes mellitus",
        "concept_code": "237599002",
        "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": "Subsumes",
        "relationship_name": "Subsumes",
        "hierarchy_level": 2,
        "valid_start_date": "2002-01-31",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      }
    ],
    "hierarchy_summary": {
      "total_descendants": 847,
      "max_hierarchy_depth": 6,
      "unique_vocabularies": ["SNOMED"],
      "relationship_types_used": ["Subsumes"]
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 847,
      "total_pages": 9,
      "has_next": true,
      "has_previous": false
    },
    "request_id": "req_descendants_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}
This endpoint returns all descendant concepts (children, grandchildren, etc.) for a specific concept, allowing exploration of more specific terms and sub-classifications within the medical vocabulary hierarchy.

​
Path Parameters

​
concept_id
integer
required
The unique identifier of the concept to retrieve descendants for
Example: 73211009 (Diabetes mellitus)

​
Query Parameters

​
vocabulary_ids
string
Filter descendants to specific vocabularies (comma-separated)
Example: SNOMED,ICD10CM
​
domain_ids
string
Filter descendants to specific domains (comma-separated)
Example: Condition,Drug
​
max_levels
integer
default:"10"
Maximum number of hierarchy levels to traverse downward
Range: 1-20
​
relationship_types
string
Relationship types to follow for hierarchy traversal. Spaces must be URL-encoded (%20) in URLs.
Default: Is a
Allowed values: Is a, Has part, Subsumes, Part of, Has ingredient, RxNorm has dose form
Example: Is%20a,Has%20part (URL-encoded)
​
include_distance
boolean
default:"false"
Include hierarchy_level field for each descendant (distance from source concept)
​
include_paths
boolean
default:"false"
Include path_length field for each descendant
​
include_invalid
boolean
default:"true"
Include deprecated/invalid concepts in descendants (default excludes them)
​
page
integer
default:"1"
Page number for pagination (1-based)
​
page_size
integer
default:"20"
Number of descendant concepts to return per page (max 1000)
​
vocab_release
string
Specific vocabulary release version to query
Example: 2025.1

​
Response

​
concept_id
integer
The concept ID for which descendants were retrieved
​
concept_name
string
Standard name of the source concept
​
vocabulary_id
string
Vocabulary containing the source concept
​
descendants
array
Array of descendant concepts in hierarchical order
​
hierarchy_summary
object
Summary statistics about the descendant hierarchy
​
meta
object
Response metadata and pagination information
curl -X GET "https://api.omophub.com/v1/concepts/73211009/descendants?include_distance=true&max_levels=3" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "concept_id": 73211009,
    "concept_name": "Diabetes mellitus",
    "vocabulary_id": "SNOMED",
    "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",
        "hierarchy_level": 1,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "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",
        "hierarchy_level": 1,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "concept_id": 237599002,
        "concept_name": "Insulin dependent diabetes mellitus",
        "concept_code": "237599002",
        "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": "Subsumes",
        "relationship_name": "Subsumes",
        "hierarchy_level": 2,
        "valid_start_date": "2002-01-31",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      }
    ],
    "hierarchy_summary": {
      "total_descendants": 847,
      "max_hierarchy_depth": 6,
      "unique_vocabularies": ["SNOMED"],
      "relationship_types_used": ["Subsumes"]
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 847,
      "total_pages": 9,
      "has_next": true,
      "has_previous": false
    },
    "request_id": "req_descendants_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

Note: Examples assume a preconfigured client from new OMOPHub(). For direct usage:
TypeScript
import { OMOPHub } from '@omophub/omophub-node';
const client = new OMOPHub();
const { data } = await client.hierarchy.descendants(73211009);

​
Basic Descendant Retrieval

Get all descendants for a specific concept:
TypeScript
const { data: descendants } = await client.hierarchy.descendants(73211009);

​
Limited Hierarchy Depth

Retrieve descendants up to a specific number of levels:
TypeScript
const { data: nearDescendants } = await client.hierarchy.descendants(73211009, { maxLevels: 2 });

​
Domain-Specific Descendants

Filter descendants to specific medical domains:
TypeScript
const { data: conditionDescendants } = await client.hierarchy.descendants(73211009, {
  domainIds: ['Condition'],
});

​
Detailed Descendant Information

Get descendants with hierarchy levels and path information:
TypeScript
const { data: detailedData } = await client.hierarchy.descendants(73211009, {
  includeDistance: true,
  includePaths: true,
});

​
Notes

  • Descendant traversal follows “Is a” relationships by default, but can include other relationship types
  • Large hierarchies may contain thousands of descendants - use pagination and filtering appropriately
  • Standard concepts are prioritized unless explicitly disabled
  • Some medical concepts may have very deep hierarchies (6+ levels)
  • Cross-vocabulary concepts may have descendants from multiple vocabularies
  • Deprecated concepts are excluded from descendants unless specifically requested with include_invalid=true