Skip to main content
GET
/
v1
/
concepts
/
{concept_id}
/
ancestors
curl -X GET "https://api.omophub.com/v1/concepts/201826/ancestors?include_paths=true&include_distance=true&max_levels=5" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

{
  "success": true,
  "data": {
    "concept_id": 201826,
    "concept_name": "Type 2 diabetes mellitus",
    "vocabulary_id": "SNOMED",
  "ancestors": [
    {
      "concept_id": 73211009,
      "concept_name": "Diabetes mellitus",
      "concept_code": "73211009",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S",
      "relationship_type": "Is a",
      "hierarchy_level": 1,
      "classification_paths": [
        {
          "path_id": "path_1",
          "path_concepts": [201826, 73211009, 362969004, 64572001, 404684003, 138875005],
          "path_names": [
            "Type 2 diabetes mellitus",
            "Diabetes mellitus", 
            "Disorder of endocrine system",
            "Disease",
            "Clinical finding",
            "SNOMED CT Concept"
          ],
          "path_length": 6
        }
      ],
      "valid_start_date": "1970-01-01T00:00:00Z",
      "valid_end_date": "2099-12-31T00:00:00Z"
    },
    {
      "concept_id": 362969004,
      "concept_name": "Disorder of endocrine system",
      "concept_code": "362969004",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S",
      "relationship_type": "Is a",
      "hierarchy_level": 2,
      "valid_start_date": "2002-01-31T00:00:00Z",
      "valid_end_date": "2099-12-31T00:00:00Z"
    },
    {
      "concept_id": 64572001,
      "concept_name": "Disease",
      "concept_code": "64572001", 
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S",
      "relationship_type": "Is a",
      "hierarchy_level": 3,
      "valid_start_date": "1970-01-01T00:00:00Z",
      "valid_end_date": "2099-12-31T00:00:00Z"
    }
  ],
  "hierarchy_summary": {
    "total_ancestors": 3,
    "max_hierarchy_depth": 5,
    "unique_vocabularies": ["SNOMED"],
    "relationship_types_used": ["Is a"],
    "classification_count": 1
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 3,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    },
    "request_id": "req_ancestors_201826_20241222_103100",
    "timestamp": "2024-12-22T10:31:00Z",
    "vocab_release": "2025.2"
  }
}
This endpoint returns the complete ancestor hierarchy for a specific concept, including parent concepts, grandparents, and all higher-level classifications up to the root of the vocabulary hierarchy.

​
Path Parameters

​
concept_id
integer
required
The unique identifier of the concept to retrieve ancestors for
Example: 201826 (Type 2 diabetes mellitus)

​
Query Parameters

​
vocabulary_id
string
Filter ancestors to specific vocabulary (useful for cross-vocabulary concepts)
Example: SNOMED
​
max_levels
integer
Maximum number of hierarchy levels to traverse (default: unlimited)
Range: 1-10
​
relationship_types
string
Relationship types to follow for hierarchy traversal. Spaces must be percent-encoded when used in query strings (e.g., “Is%20a,Part%20of”).
Default: Is a
Allowed values: Is a, Part of, Has part, Subsumes, Has ingredient, RxNorm has dose form
Example: Is%20a,Part%20of (URL-encoded)
​
include_paths
boolean
default:"false"
Include complete classification paths from concept to root
​
include_distance
boolean
default:"false"
Include hierarchical distance (level) for each ancestor
​
standard_only
boolean
default:"true"
Only return standard concepts in the hierarchy
​
include_deprecated
boolean
default:"false"
Include deprecated/invalid concepts in ancestry
​
page_size
integer
default:"100"
Number of ancestor concepts to return per page (max 1000)
​
page
integer
default:"1"
Page number for pagination (1-based)

​
Response

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

{
  "success": true,
  "data": {
    "concept_id": 201826,
    "concept_name": "Type 2 diabetes mellitus",
    "vocabulary_id": "SNOMED",
  "ancestors": [
    {
      "concept_id": 73211009,
      "concept_name": "Diabetes mellitus",
      "concept_code": "73211009",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S",
      "relationship_type": "Is a",
      "hierarchy_level": 1,
      "classification_paths": [
        {
          "path_id": "path_1",
          "path_concepts": [201826, 73211009, 362969004, 64572001, 404684003, 138875005],
          "path_names": [
            "Type 2 diabetes mellitus",
            "Diabetes mellitus", 
            "Disorder of endocrine system",
            "Disease",
            "Clinical finding",
            "SNOMED CT Concept"
          ],
          "path_length": 6
        }
      ],
      "valid_start_date": "1970-01-01T00:00:00Z",
      "valid_end_date": "2099-12-31T00:00:00Z"
    },
    {
      "concept_id": 362969004,
      "concept_name": "Disorder of endocrine system",
      "concept_code": "362969004",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S",
      "relationship_type": "Is a",
      "hierarchy_level": 2,
      "valid_start_date": "2002-01-31T00:00:00Z",
      "valid_end_date": "2099-12-31T00:00:00Z"
    },
    {
      "concept_id": 64572001,
      "concept_name": "Disease",
      "concept_code": "64572001", 
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S",
      "relationship_type": "Is a",
      "hierarchy_level": 3,
      "valid_start_date": "1970-01-01T00:00:00Z",
      "valid_end_date": "2099-12-31T00:00:00Z"
    }
  ],
  "hierarchy_summary": {
    "total_ancestors": 3,
    "max_hierarchy_depth": 5,
    "unique_vocabularies": ["SNOMED"],
    "relationship_types_used": ["Is a"],
    "classification_count": 1
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 3,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    },
    "request_id": "req_ancestors_201826_20241222_103100",
    "timestamp": "2024-12-22T10:31:00Z",
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

​
Basic Ancestor Retrieval

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

​
Limited Hierarchy Depth

Retrieve ancestors up to a specific number of levels: 
const nearAncestors = await fetch('/v1/concepts/201826/ancestors?max_levels=3');

​
Classification Path Analysis

Get complete classification paths from concept to root: 
const pathData = await fetch('/v1/concepts/201826/ancestors?include_paths=true&include_distance=true');

​
Cross-Vocabulary Hierarchy

Analyze ancestors within specific vocabulary: 
const snomedAncestors = await fetch('/v1/concepts/201826/ancestors?vocabulary_id=SNOMED');

​
Multiple Relationship Types

Follow different types of hierarchical relationships: 
const extendedHierarchy = await fetch('/v1/concepts/201826/ancestors?relationship_types=Is%20a,Part%20of');

​
Notes

  • Hierarchy traversal follows “Is a” relationships by default, but can be customized
  • Some concepts may have multiple classification paths to different root concepts
  • Cross-vocabulary concepts may have ancestors in different vocabularies
  • Standard concepts are prioritized in hierarchy traversal unless explicitly disabled
  • Deprecated concepts are excluded from ancestry unless specifically requested
  • Maximum hierarchy depth is typically 6-8 levels for most medical vocabularies