Skip to main content
GET
/
v1
/
concepts
/
{concept_id}
/
descendants
curl -X GET "https://api.omophub.com/v1/concepts/73211009/descendants?include_distance=true&max_levels=3&include_synonyms=true" \
  -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",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "relationship_type": "Is a",
        "hierarchy_level": 1,
        "parent_concept_id": 73211009,
        "synonyms": [
          {
            "concept_synonym_name": "Type II diabetes mellitus",
            "language_concept_id": 4180186,
            "language_concept_name": "English"
          },
          {
            "concept_synonym_name": "Adult-onset diabetes",
            "language_concept_id": 4180186,
            "language_concept_name": "English"
          }
        ],
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31"
      },
      {
        "concept_id": 46635009,
        "concept_name": "Type 1 diabetes mellitus",
        "concept_code": "46635009",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "relationship_type": "Is a",
        "hierarchy_level": 1,
        "parent_concept_id": 73211009,
        "synonyms": [
          {
            "concept_synonym_name": "Type I diabetes mellitus",
            "language_concept_id": 4180186,
            "language_concept_name": "English"
          },
          {
            "concept_synonym_name": "Juvenile diabetes",
            "language_concept_id": 4180186,
            "language_concept_name": "English"
          }
        ],
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31"
      },
      {
        "concept_id": 199223000,
        "concept_name": "Diabetes mellitus due to genetic defect",
        "concept_code": "199223000",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "relationship_type": "Is a",
        "hierarchy_level": 1,
        "parent_concept_id": 73211009,
        "valid_start_date": "2002-01-31",
        "valid_end_date": "2099-12-31"
      },
      {
        "concept_id": 237599002,
        "concept_name": "Insulin dependent diabetes mellitus",
        "concept_code": "237599002",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "relationship_type": "Is a",
        "hierarchy_level": 2,
        "parent_concept_id": 46635009,
        "valid_start_date": "2002-01-31",
        "valid_end_date": "2099-12-31"
      }
    ],
    "hierarchy_summary": {
      "total_descendants": 847,
      "max_hierarchy_depth": 6,
      "direct_children": 23,
      "unique_vocabularies": ["SNOMED"],
      "domain_distribution": {
        "Condition": 801,
        "Procedure": 32,
        "Observation": 14
      },
      "concept_class_distribution": {
        "Clinical Finding": 723,
        "Procedure": 89,
        "Observable Entity": 35
      }
    }
  },
  "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_id
string
Filter descendants to specific vocabulary
Example: SNOMED
​
max_levels
integer
Maximum number of hierarchy levels to traverse downward (default: 10)
Range: 1-10. Values above 10 are capped at 10 by the server for performance reasons. Omitting this parameter defaults to the maximum of 10 levels.
​
relationship_types
string
Relationship types to follow for hierarchy traversal. Accepts CSV string (comma-separated values) or array. Spaces must be URL-encoded (%20) in URLs. Individual entries are trimmed and matched case-insensitively.
Default: Is a
Allowed values: Is a, Has part, Subsumes, Part of, Has ingredient, RxNorm has dose form
CSV Example: Is%20a,Has%20part (URL-encoded)
Array Example: ["Is a", "Has part"]
​
include_distance
boolean
default:"false"
Include hierarchical distance (level) for each descendant
​
standard_only
boolean
default:"true"
Filter results by standard_concept flag. When true, restricts results to concepts with standard_concept=‘S’ (excludes classification ‘C’ and null values). When false, returns concepts regardless of standard_concept.
​
include_deprecated
boolean
default:"false"
Include deprecated/invalid concepts in descendants. When false, excludes deprecated/invalid concepts; when true, includes them. This filter is applied after standard_only filtering.
​
domain_ids
string
Comma-separated list of domain IDs to filter descendants
Example: Condition,Drug
​
concept_class_ids
string
Comma-separated list of concept class IDs to filter descendants
Example: Clinical Finding,Procedure
​
include_synonyms
boolean
default:"false"
Include synonym information for descendant concepts
​
page_size
integer
default:"100"
Number of descendant concepts to return per page. Values over 1000 are automatically capped at 1000. Invalid values return HTTP 400. Results are ordered breadth-first by level, then concept_id ascending for deterministic pagination.
​
page
integer
default:"1"
Page number for pagination (1-based). Uses deterministic ordering for stable pagination.

​
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&include_synonyms=true" \
  -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",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "relationship_type": "Is a",
        "hierarchy_level": 1,
        "parent_concept_id": 73211009,
        "synonyms": [
          {
            "concept_synonym_name": "Type II diabetes mellitus",
            "language_concept_id": 4180186,
            "language_concept_name": "English"
          },
          {
            "concept_synonym_name": "Adult-onset diabetes",
            "language_concept_id": 4180186,
            "language_concept_name": "English"
          }
        ],
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31"
      },
      {
        "concept_id": 46635009,
        "concept_name": "Type 1 diabetes mellitus",
        "concept_code": "46635009",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "relationship_type": "Is a",
        "hierarchy_level": 1,
        "parent_concept_id": 73211009,
        "synonyms": [
          {
            "concept_synonym_name": "Type I diabetes mellitus",
            "language_concept_id": 4180186,
            "language_concept_name": "English"
          },
          {
            "concept_synonym_name": "Juvenile diabetes",
            "language_concept_id": 4180186,
            "language_concept_name": "English"
          }
        ],
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31"
      },
      {
        "concept_id": 199223000,
        "concept_name": "Diabetes mellitus due to genetic defect",
        "concept_code": "199223000",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "relationship_type": "Is a",
        "hierarchy_level": 1,
        "parent_concept_id": 73211009,
        "valid_start_date": "2002-01-31",
        "valid_end_date": "2099-12-31"
      },
      {
        "concept_id": 237599002,
        "concept_name": "Insulin dependent diabetes mellitus",
        "concept_code": "237599002",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "relationship_type": "Is a",
        "hierarchy_level": 2,
        "parent_concept_id": 46635009,
        "valid_start_date": "2002-01-31",
        "valid_end_date": "2099-12-31"
      }
    ],
    "hierarchy_summary": {
      "total_descendants": 847,
      "max_hierarchy_depth": 6,
      "direct_children": 23,
      "unique_vocabularies": ["SNOMED"],
      "domain_distribution": {
        "Condition": 801,
        "Procedure": 32,
        "Observation": 14
      },
      "concept_class_distribution": {
        "Clinical Finding": 723,
        "Procedure": 89,
        "Observable Entity": 35
      }
    }
  },
  "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 with base URL https://api.omophub.com and authentication headers. For direct usage: 
const response = await fetch('https://api.omophub.com/v1/concepts/73211009/descendants', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
});

​
Basic Descendant Retrieval

Get all descendants for a specific concept: 
const descendants = await fetch('/v1/concepts/73211009/descendants');

​
Limited Hierarchy Depth

Retrieve descendants up to a specific number of levels: 
const nearDescendants = await fetch('/v1/concepts/73211009/descendants?max_levels=2');

​
Domain-Specific Descendants

Filter descendants to specific medical domains: 
const conditionDescendants = await fetch('/v1/concepts/73211009/descendants?domain_ids=Condition');

​
Detailed Descendant Information

Get descendants with synonyms and hierarchy levels: 
const detailedData = await fetch('/v1/concepts/73211009/descendants?include_synonyms=true&include_distance=true');

​
Concept Class Filtering

Find descendants of specific concept classes: 
const procedures = await fetch('/v1/concepts/73211009/descendants?concept_class_ids=Procedure');

​
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
  • Synonym information adds significant detail but increases response size