Skip to main content
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:"true"
Include deprecated/invalid concepts in ancestry (default excludes them)
​
page
integer
default:"1"
Page number for pagination (1-based)
​
page_size
integer
default:"20"
Number of ancestor concepts to return per page (max 1000)
​
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
​
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",
        "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'],
});

​
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