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"

import { OMOPHub } from '@omophub/omophub-node';

const client = new OMOPHub();
const { data: ancestorData } = await client.hierarchy.ancestors(201826, {
  includePaths: true,
  includeDistance: true,
  maxLevels: 5,
});

console.log(`Found ${ancestorData?.hierarchy_summary.total_ancestors} ancestors`);
console.log('First ancestor:', ancestorData?.ancestors[0]?.concept_name);

import requests

concept_id = 201826  # Type 2 diabetes mellitus
url = f"https://api.omophub.com/v1/concepts/{concept_id}/ancestors"
params = {
    "include_paths": True,
    "include_distance": True,
    "max_levels": 5
}

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

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

print(f"Concept: {ancestor_data['data']['concept_name']}")
print(f"Total ancestors: {ancestor_data['data']['hierarchy_summary']['total_ancestors']}")

for ancestor in ancestor_data['data']['ancestors'][:5]:
    level = ancestor.get('level', 'Unknown')
    print(f"Level {level}: {ancestor['concept_name']} ({ancestor['concept_id']})")

{
  "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",
        "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",
        "hierarchy_level": 1,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "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": 2,
        "min_levels_of_separation": 2,
        "max_levels_of_separation": 2,
        "relationship_id": "Is a",
        "relationship_name": "Is a",
        "hierarchy_level": 2,
        "valid_start_date": "2002-01-31",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "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": 3,
        "min_levels_of_separation": 3,
        "max_levels_of_separation": 3,
        "relationship_id": "Is a",
        "relationship_name": "Is a",
        "hierarchy_level": 3,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      }
    ],
    "hierarchy_summary": {
      "total_ancestors": 3,
      "max_hierarchy_depth": 3,
      "unique_vocabularies": ["SNOMED"],
      "relationship_types_used": ["Is a"]
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 3,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    },
    "request_id": "req_ancestors_201826_20250104_103100",
    "timestamp": "2025-01-04T10:31:00Z",
    "vocab_release": "2025.1"
  }
}

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"

import { OMOPHub } from '@omophub/omophub-node';

const client = new OMOPHub();
const { data: ancestorData } = await client.hierarchy.ancestors(201826, {
  includePaths: true,
  includeDistance: true,
  maxLevels: 5,
});

console.log(`Found ${ancestorData?.hierarchy_summary.total_ancestors} ancestors`);
console.log('First ancestor:', ancestorData?.ancestors[0]?.concept_name);

import requests

concept_id = 201826  # Type 2 diabetes mellitus
url = f"https://api.omophub.com/v1/concepts/{concept_id}/ancestors"
params = {
    "include_paths": True,
    "include_distance": True,
    "max_levels": 5
}

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

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

print(f"Concept: {ancestor_data['data']['concept_name']}")
print(f"Total ancestors: {ancestor_data['data']['hierarchy_summary']['total_ancestors']}")

for ancestor in ancestor_data['data']['ancestors'][:5]:
    level = ancestor.get('level', 'Unknown')
    print(f"Level {level}: {ancestor['concept_name']} ({ancestor['concept_id']})")

{
  "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",
        "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",
        "hierarchy_level": 1,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "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": 2,
        "min_levels_of_separation": 2,
        "max_levels_of_separation": 2,
        "relationship_id": "Is a",
        "relationship_name": "Is a",
        "hierarchy_level": 2,
        "valid_start_date": "2002-01-31",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "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": 3,
        "min_levels_of_separation": 3,
        "max_levels_of_separation": 3,
        "relationship_id": "Is a",
        "relationship_name": "Is a",
        "hierarchy_level": 3,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      }
    ],
    "hierarchy_summary": {
      "total_ancestors": 3,
      "max_hierarchy_depth": 3,
      "unique_vocabularies": ["SNOMED"],
      "relationship_types_used": ["Is a"]
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 3,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    },
    "request_id": "req_ancestors_201826_20250104_103100",
    "timestamp": "2025-01-04T10:31:00Z",
    "vocab_release": "2025.1"
  }
}

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

integer

required

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

Query Parameters

string

Filter ancestors to specific vocabularies (comma-separated)
Example: SNOMED,ICD10CM

string

Filter ancestors to specific domains (comma-separated)
Example: Condition,Observation

integer

default:"10"

Maximum number of hierarchy levels to traverse
Range: 1-20

This endpoint always traverses the Is a hierarchy. It reads OMOP’s precomputed concept_ancestor closure, which stores only transitive Is a ancestry - it has no relationship column to filter on. Every ancestor is therefore returned with relationship_id: "Is a".A relationship_types parameter is accepted for backwards compatibility but has no effect here: passing Part of, or even a nonexistent relationship, returns the same Is a ancestors. To traverse other relationship types, use GET /v1/concepts/{concept_id}/relationships or POST /v1/concepts/relationships/traverse, which query concept_relationship directly.

boolean

default:"false"

Include hierarchy_level field for each ancestor (distance from source concept)

boolean

default:"false"

Include path_length field for each ancestor

boolean

default:"false"

Include deprecated/invalid concepts in ancestry (by default they are excluded)

integer

default:"1"

Page number for pagination (1-based)

integer

default:"5000"

Maximum size of the ancestor set to retrieve before pagination is applied.
Range: 1-5000
Defaults to the maximum, so paging through the response returns every ancestor that matches this request - those within max_levels and any vocabulary_ids / domain_ids filters you supplied. (relationship_types is not applied - see above.) It is not necessarily the concept’s entire ancestry: max_levels defaults to 10, so more distant ancestors are excluded, and truncated does not flag that (it reports the row cap only). Pass max_levels=20 if you need the full ancestry.

integer

default:"100"

Number of ancestor concepts to return per page. Values above 200 are clamped to 200.

string

Specific vocabulary release version to query
Example: 2025.1

Response

integer

The concept ID for which ancestors were retrieved

string

Standard name of the source concept

string

Vocabulary containing the source concept

array

Array of ancestor concepts in hierarchical order

Show Ancestor Concept Object

integer

Unique identifier for the ancestor concept

string

Standard name of the ancestor concept

string

Original code from the vocabulary

string

Vocabulary containing this ancestor concept

string

Human-readable vocabulary name

string

Domain classification of the ancestor

string

Concept class identifier

string

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

integer

Distance from source concept (always present)

integer

Minimum levels of separation from source concept

integer

Maximum levels of separation from source concept

string

Relationship type ID (e.g., “Is a”)

string

Relationship type name (e.g., “Is a”)

integer

Distance from source concept (only when include_distance=true, same as level)

integer

Path length from source concept (only when include_paths=true, same as level)

string

Date when concept became valid (ISO format)

string

Date when concept became invalid (ISO format)

string

Reason for concept invalidation if applicable

object

Summary statistics about the ancestor hierarchy

Show Hierarchy Summary Object

integer

Total number of ancestor concepts found

integer

Maximum depth of the hierarchy tree

array

List of vocabulary IDs represented in ancestors

array

List of relationship type IDs found in hierarchy

object

Response metadata and pagination information

Show Metadata Object

object

integer

Current page number

integer

Items per page

integer

Total ancestor concepts

integer

Total number of pages

boolean

Whether next page exists

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"

import { OMOPHub } from '@omophub/omophub-node';

const client = new OMOPHub();
const { data: ancestorData } = await client.hierarchy.ancestors(201826, {
  includePaths: true,
  includeDistance: true,
  maxLevels: 5,
});

console.log(`Found ${ancestorData?.hierarchy_summary.total_ancestors} ancestors`);
console.log('First ancestor:', ancestorData?.ancestors[0]?.concept_name);

import requests

concept_id = 201826  # Type 2 diabetes mellitus
url = f"https://api.omophub.com/v1/concepts/{concept_id}/ancestors"
params = {
    "include_paths": True,
    "include_distance": True,
    "max_levels": 5
}

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

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

print(f"Concept: {ancestor_data['data']['concept_name']}")
print(f"Total ancestors: {ancestor_data['data']['hierarchy_summary']['total_ancestors']}")

for ancestor in ancestor_data['data']['ancestors'][:5]:
    level = ancestor.get('level', 'Unknown')
    print(f"Level {level}: {ancestor['concept_name']} ({ancestor['concept_id']})")

{
  "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",
        "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",
        "hierarchy_level": 1,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "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": 2,
        "min_levels_of_separation": 2,
        "max_levels_of_separation": 2,
        "relationship_id": "Is a",
        "relationship_name": "Is a",
        "hierarchy_level": 2,
        "valid_start_date": "2002-01-31",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "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": 3,
        "min_levels_of_separation": 3,
        "max_levels_of_separation": 3,
        "relationship_id": "Is a",
        "relationship_name": "Is a",
        "hierarchy_level": 3,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      }
    ],
    "hierarchy_summary": {
      "total_ancestors": 3,
      "max_hierarchy_depth": 3,
      "unique_vocabularies": ["SNOMED"],
      "relationship_types_used": ["Is a"]
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 3,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    },
    "request_id": "req_ancestors_201826_20250104_103100",
    "timestamp": "2025-01-04T10:31:00Z",
    "vocab_release": "2025.1"
  }
}

Usage Examples

Basic Ancestor Retrieval

Get all ancestors for a specific concept:

TypeScript

const { data: ancestors } = await client.hierarchy.ancestors(201826);

Limited Hierarchy Depth

Retrieve ancestors up to a specific number of levels:

TypeScript

const { data: nearAncestors } = await client.hierarchy.ancestors(201826, { maxLevels: 3 });

Classification Path Analysis

Get complete classification paths from concept to root:

TypeScript

const { data: pathData } = await client.hierarchy.ancestors(201826, {
  includePaths: true,
  includeDistance: true,
});

Cross-Vocabulary Hierarchy

Analyze ancestors within specific vocabulary:

TypeScript

const { data: snomedAncestors } = await client.hierarchy.ancestors(201826, {
  vocabularyIds: ['SNOMED'],
});

Multiple Relationship Types

Follow different types of hierarchical relationships:

TypeScript

const { data: extendedHierarchy } = await client.hierarchy.ancestors(201826, {
  relationshipTypes: ['Is a', 'Part of'],
});

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

API Reference

Search

Concepts

Concept Hierarchy

Mappings

FHIR Resolver

Relationships

Domains & Classifications

Vocabularies

Path Parameters

Query Parameters

Response

Usage Examples

Basic Ancestor Retrieval

Limited Hierarchy Depth

Classification Path Analysis

Cross-Vocabulary Hierarchy

Multiple Relationship Types

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

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