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

concept_id

integer

required

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

Query Parameters

vocabulary_ids

string

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

domain_ids

string

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

max_levels

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.

include_distance

boolean

default:"false"

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

include_paths

boolean

default:"false"

Include path_length field for each ancestor

include_invalid

boolean

default:"false"

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

page

integer

default:"1"

Page number for pagination (1-based)

max_results

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.

page_size

integer

default:"100"

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

vocab_release

string

Specific vocabulary release version to query
Example: 2025.1

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

vocabulary_name

string

Human-readable vocabulary name

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)

level

integer

Distance from source concept (always present)

min_levels_of_separation

integer

Minimum levels of separation from source concept

max_levels_of_separation

integer

Maximum levels of separation from source concept

relationship_id

string

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

relationship_name

string

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

hierarchy_level

integer

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

path_length

integer

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

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 vocabulary IDs represented in ancestors

relationship_types_used

array

List of relationship type IDs found in hierarchy

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"

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

Batch Hierarchy Queries Get Concept Descendants

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