Get Concept 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"
  }
}

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

Show Ancestor Concept Object

concept_id

integer

Unique identifier for the ancestor concept

concept_name

string

Standard name of the ancestor concept

concept_code

string

Original code from the vocabulary

vocabulary_id

string

Vocabulary containing this ancestor concept

domain_id

string

Domain classification of the ancestor

concept_class_id

string

Concept class identifier

standard_concept

string

Standard concept designation (‘S’, ‘C’, or null)

relationship_type

string

Type of relationship to child concept

hierarchy_level

integer

Distance from original concept (when include_distance=true)

classification_paths

array

Complete paths from concept to root (when include_paths=true)

Show Classification Path Object

path_id

string

Unique identifier for this classification path

path_concepts

array

Ordered array of concept IDs from source to root

path_names

array

Ordered array of concept names corresponding to path_concepts

path_length

integer

Number of concepts in this path

valid_start_date

string

Date when concept became valid (ISO format)

valid_end_date

string

Date when concept became invalid (ISO format)

invalid_reason

string

Reason for concept invalidation if applicable

hierarchy_summary

object

Summary statistics about the ancestor hierarchy

Show Hierarchy Summary Object

total_ancestors

integer

Total number of ancestor concepts found

max_hierarchy_depth

integer

Maximum depth of the hierarchy tree

unique_vocabularies

array

List of vocabularies represented in ancestors

relationship_types_used

array

List of relationship types found in hierarchy

classification_count

integer

Number of distinct classification paths

meta

object

Response metadata and pagination information

Show Metadata Object

pagination

object

page

integer

Current page number

page_size

integer

Items per page

total_items

integer

Total ancestor concepts

total_pages

integer

Total number of pages

has_next

boolean

Whether next page exists

has_previous

boolean

Whether previous page exists

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');

Get Concept Descendants - Retrieve child concepts
Get Concept Hierarchy - Complete hierarchy view
Get Concept Relationships - All concept relationships
Get Concept Details - Complete concept information

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

⌘I

API Reference

Concepts

Concept Hierarchy

Search

Search (Coming Soon)

Relationships

Domains & Classifications

Mappings

Vocabularies

Path Parameters

Query Parameters

Response

Usage Examples

Basic Ancestor Retrieval

Limited Hierarchy Depth

Classification Path Analysis

Cross-Vocabulary Hierarchy

Multiple Relationship Types

Notes

API Reference

Concepts

Concept Hierarchy

Search

Search (Coming Soon)

Relationships

Domains & Classifications

Mappings

Vocabularies

​Path Parameters

​Query Parameters

​Response

​Usage Examples

​Basic Ancestor Retrieval

​Limited Hierarchy Depth

​Classification Path Analysis

​Cross-Vocabulary Hierarchy

​Multiple Relationship Types

​Related Endpoints

​Notes

Path Parameters

Query Parameters

Response

Usage Examples

Basic Ancestor Retrieval

Limited Hierarchy Depth

Classification Path Analysis

Cross-Vocabulary Hierarchy

Multiple Relationship Types

Related Endpoints

Notes