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",
        "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"

{
  "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

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_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 (default excludes them)

page

integer

default:"1"

Page number for pagination (1-based)

page_size

integer

default:"100"

Number of ancestor concepts to return per page (max 1000)

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"

{
  "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:

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

Batch Hierarchy Queries Get Concept Descendants

⌘I

API Reference

Search

Concepts

Concept Hierarchy

Relationships

Domains & Classifications

Vocabularies

Mappings

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

Search

Concepts

Concept Hierarchy

Relationships

Domains & Classifications

Vocabularies

Mappings

​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