Skip to main content
POST
https://api.omophub.com
/
v1
/
concepts
/
hierarchy
/
batch
curl -X POST "https://api.omophub.com/v1/concepts/hierarchy/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "concept_id": 201826,
        "query_type": "ancestors",
        "max_levels": 5
      },
      {
        "concept_id": 4182210,
        "query_type": "descendants",
        "max_levels": 3
      },
      {
        "concept_id": 313217,
        "query_type": "both",
        "max_levels": 4,
        "relationship_types": ["Is a", "Subsumes"]
      }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      {
        "concept_id": 201826,
        "query_type": "ancestors",
        "success": true,
        "ancestors": [
          {
            "concept_id": 73211009,
            "concept_name": "Diabetes mellitus",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "level": 1,
            "relationship_type": "Is a"
          },
          {
            "concept_id": 64572001,
            "concept_name": "Disease",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "level": 2,
            "relationship_type": "Is a"
          },
          {
            "concept_id": 138875005,
            "concept_name": "Clinical finding",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "level": 3,
            "relationship_type": "Is a"
          }
        ],
        "summary": {
          "total_ancestors": 3,
          "total_descendants": 0,
          "max_ancestor_level": 3,
          "max_descendant_level": 0,
          "vocabularies_involved": ["SNOMED"]
        }
      },
      {
        "concept_id": 4182210,
        "query_type": "descendants",
        "success": true,
        "descendants": [
          {
            "concept_id": 320128,
            "concept_name": "Essential hypertension",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "level": 1,
            "relationship_type": "Is a"
          },
          {
            "concept_id": 443767,
            "concept_name": "Secondary hypertension",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "level": 1,
            "relationship_type": "Is a"
          }
        ],
        "summary": {
          "total_ancestors": 0,
          "total_descendants": 2,
          "max_ancestor_level": 0,
          "max_descendant_level": 1,
          "vocabularies_involved": ["SNOMED"]
        }
      },
      {
        "concept_id": 313217,
        "query_type": "both",
        "success": true,
        "ancestors": [
          {
            "concept_id": 49436004,
            "concept_name": "Atrial fibrillation and flutter",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "level": 1,
            "relationship_type": "Is a"
          }
        ],
        "descendants": [
          {
            "concept_id": 440059007,
            "concept_name": "Paroxysmal atrial fibrillation",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "level": 1,
            "relationship_type": "Subsumes"
          }
        ],
        "summary": {
          "total_ancestors": 1,
          "total_descendants": 1,
          "max_ancestor_level": 1,
          "max_descendant_level": 1,
          "vocabularies_involved": ["SNOMED"]
        }
      }
    ],
    "batch_summary": {
      "total_queries": 3,
      "successful_queries": 3,
      "failed_queries": 0,
      "total_concepts_returned": 7,
      "processing_time_ms": 245
    }
  },
  "meta": {
    "request_id": "req_batch_hierarchy_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

​
Overview

This endpoint allows you to perform multiple hierarchy queries (ancestors, descendants, or both) for multiple concepts in a single API call. This is highly efficient for applications that need hierarchical information for many concepts simultaneously.

​
Request Body

​
queries
array
required
Array of hierarchy query requests

​
Query Parameters

​
vocab_release
string
Specific vocabulary release version (e.g., “2024.1”)
​
include_invalid
boolean
default:"false"
Include relationships to invalid/deprecated concepts

​
Response

​
success
boolean
required
Indicates whether the request was successful
​
results
array
required
Array of hierarchy query results matching the input order
​
batch_summary
object
required
Summary statistics for the entire batch
curl -X POST "https://api.omophub.com/v1/concepts/hierarchy/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "concept_id": 201826,
        "query_type": "ancestors",
        "max_levels": 5
      },
      {
        "concept_id": 4182210,
        "query_type": "descendants",
        "max_levels": 3
      },
      {
        "concept_id": 313217,
        "query_type": "both",
        "max_levels": 4,
        "relationship_types": ["Is a", "Subsumes"]
      }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      {
        "concept_id": 201826,
        "query_type": "ancestors",
        "success": true,
        "ancestors": [
          {
            "concept_id": 73211009,
            "concept_name": "Diabetes mellitus",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "level": 1,
            "relationship_type": "Is a"
          },
          {
            "concept_id": 64572001,
            "concept_name": "Disease",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "level": 2,
            "relationship_type": "Is a"
          },
          {
            "concept_id": 138875005,
            "concept_name": "Clinical finding",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "level": 3,
            "relationship_type": "Is a"
          }
        ],
        "summary": {
          "total_ancestors": 3,
          "total_descendants": 0,
          "max_ancestor_level": 3,
          "max_descendant_level": 0,
          "vocabularies_involved": ["SNOMED"]
        }
      },
      {
        "concept_id": 4182210,
        "query_type": "descendants",
        "success": true,
        "descendants": [
          {
            "concept_id": 320128,
            "concept_name": "Essential hypertension",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "level": 1,
            "relationship_type": "Is a"
          },
          {
            "concept_id": 443767,
            "concept_name": "Secondary hypertension",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "level": 1,
            "relationship_type": "Is a"
          }
        ],
        "summary": {
          "total_ancestors": 0,
          "total_descendants": 2,
          "max_ancestor_level": 0,
          "max_descendant_level": 1,
          "vocabularies_involved": ["SNOMED"]
        }
      },
      {
        "concept_id": 313217,
        "query_type": "both",
        "success": true,
        "ancestors": [
          {
            "concept_id": 49436004,
            "concept_name": "Atrial fibrillation and flutter",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "level": 1,
            "relationship_type": "Is a"
          }
        ],
        "descendants": [
          {
            "concept_id": 440059007,
            "concept_name": "Paroxysmal atrial fibrillation",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "level": 1,
            "relationship_type": "Subsumes"
          }
        ],
        "summary": {
          "total_ancestors": 1,
          "total_descendants": 1,
          "max_ancestor_level": 1,
          "max_descendant_level": 1,
          "vocabularies_involved": ["SNOMED"]
        }
      }
    ],
    "batch_summary": {
      "total_queries": 3,
      "successful_queries": 3,
      "failed_queries": 0,
      "total_concepts_returned": 7,
      "processing_time_ms": 245
    }
  },
  "meta": {
    "request_id": "req_batch_hierarchy_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

​
Simple Batch Ancestors

Get ancestors for multiple concepts: 
{
  "queries": [
    {"concept_id": 201826, "query_type": "ancestors"},
    {"concept_id": 4182210, "query_type": "ancestors"},
    {"concept_id": 313217, "query_type": "ancestors"}
  ]
}

​
Mixed Query Types

Combine different query types in one batch: 
{
  "queries": [
    {"concept_id": 201826, "query_type": "ancestors", "max_levels": 5},
    {"concept_id": 4182210, "query_type": "descendants", "max_levels": 3},
    {"concept_id": 313217, "query_type": "both", "max_levels": 4}
  ]
}

​
Advanced Filtering

Use relationship and vocabulary filters: 
{
  "queries": [
    {
      "concept_id": 201826,
      "query_type": "both",
      "max_levels": 5,
      "relationship_types": ["Is a", "Subsumes"],
      "vocabulary_ids": ["SNOMED", "ICD10CM"],
      "include_self": true
    }
  ]
}

​
Important Notes

  • Batch size limit: Maximum 50 queries per batch request
  • Performance optimization: Batch processing is significantly faster than individual requests
  • Error handling: Individual query failures don’t affect other queries in the batch
  • Result order: Results are returned in the same order as input queries
  • Memory considerations: Large batches with deep hierarchies may have longer response times
  • Rate limiting: Batch requests count as single requests for rate limiting purposes