Batch Hierarchy Queries - OMOPHub.com API

curl -X POST "https://api.omophub.com/v1/concepts/hierarchy/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "query_id": "q1",
        "concept_id": 201826,
        "operation": "ancestors",
        "params": {
          "max_levels": 5
        }
      },
      {
        "query_id": "q2",
        "concept_id": 4182210,
        "operation": "descendants",
        "params": {
          "max_levels": 3
        }
      },
      {
        "query_id": "q3",
        "concept_id": 313217,
        "operation": "hierarchy",
        "params": {
          "max_levels": 4,
          "relationship_types": ["Is a"]
        }
      }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      {
        "query_id": "q1",
        "concept_id": 201826,
        "operation": "ancestors",
        "success": true,
        "data": {
          "ancestors": [
            {
              "concept_id": 73211009,
              "concept_name": "Diabetes mellitus",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S",
              "level": 1
            },
            {
              "concept_id": 64572001,
              "concept_name": "Disease",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S",
              "level": 2
            }
          ],
          "total_count": 2
        }
      },
      {
        "query_id": "q2",
        "concept_id": 4182210,
        "operation": "descendants",
        "success": true,
        "data": {
          "descendants": [
            {
              "concept_id": 320128,
              "concept_name": "Essential hypertension",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S",
              "level": 1
            }
          ],
          "total_count": 1
        }
      },
      {
        "query_id": "q3",
        "concept_id": 313217,
        "operation": "hierarchy",
        "success": true,
        "data": {
          "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
            }
          ],
          "descendants": [],
          "total_count": 1
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_batch_hierarchy_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.1"
  }
}

curl -X POST "https://api.omophub.com/v1/concepts/hierarchy/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "query_id": "q1",
        "concept_id": 201826,
        "operation": "ancestors",
        "params": {
          "max_levels": 5
        }
      },
      {
        "query_id": "q2",
        "concept_id": 4182210,
        "operation": "descendants",
        "params": {
          "max_levels": 3
        }
      },
      {
        "query_id": "q3",
        "concept_id": 313217,
        "operation": "hierarchy",
        "params": {
          "max_levels": 4,
          "relationship_types": ["Is a"]
        }
      }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      {
        "query_id": "q1",
        "concept_id": 201826,
        "operation": "ancestors",
        "success": true,
        "data": {
          "ancestors": [
            {
              "concept_id": 73211009,
              "concept_name": "Diabetes mellitus",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S",
              "level": 1
            },
            {
              "concept_id": 64572001,
              "concept_name": "Disease",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S",
              "level": 2
            }
          ],
          "total_count": 2
        }
      },
      {
        "query_id": "q2",
        "concept_id": 4182210,
        "operation": "descendants",
        "success": true,
        "data": {
          "descendants": [
            {
              "concept_id": 320128,
              "concept_name": "Essential hypertension",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S",
              "level": 1
            }
          ],
          "total_count": 1
        }
      },
      {
        "query_id": "q3",
        "concept_id": 313217,
        "operation": "hierarchy",
        "success": true,
        "data": {
          "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
            }
          ],
          "descendants": [],
          "total_count": 1
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_batch_hierarchy_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.1"
  }
}

Overview

This endpoint allows you to perform multiple hierarchy queries (ancestors, descendants, or full hierarchy) 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 (1-100 queries)

Show queries

query_id

string

required

Unique identifier for this query (used to match results)

concept_id

integer

required

The OMOP concept ID to query hierarchy for

operation

string

required

Type of hierarchy query. Options: ancestors, descendants, hierarchy, level, relationships, related, traverse

params

object

Optional parameters for the query

Show params

max_levels

integer

default:"10"

Maximum number of hierarchy levels to traverse

relationship_types

array

Array of relationship types to follow (default: [“Is a”])

vocabulary_ids

array

Limit results to specific vocabularies

domain_ids

array

Limit results to specific domains

include_invalid

boolean

default:"true"

Include relationships to invalid/deprecated concepts

Query Parameters

vocab_release

string

Specific vocabulary release version (e.g., “2025.1”)

Response

success

boolean

required

Indicates whether the request was successful

data

object

required

Response data containing batch results

Show data

results

array

required

Array of query results matching the input order

Show results

query_id

string

The query identifier from the request

concept_id

integer

The concept ID that was queried

operation

string

The operation that was performed

success

boolean

Whether this individual query succeeded

data

object

Result data if the query succeeded (structure varies by operation)

Show data (ancestors/descendants)

ancestors

array

Array of ancestor concepts (for ancestors/hierarchy operations)

Show concept object

concept_id

integer

OMOP concept ID

concept_name

string

Primary concept name

vocabulary_id

string

Source vocabulary identifier

domain_id

string

Clinical domain classification

concept_class_id

string

Concept class identifier

standard_concept

string|null

Standard concept flag (S, C, or null)

level

integer

Distance from the source concept in hierarchy

descendants

array

Array of descendant concepts (for descendants/hierarchy operations)

Show concept object

concept_id

integer

OMOP concept ID

concept_name

string

Primary concept name

vocabulary_id

string

Source vocabulary identifier

domain_id

string

Clinical domain classification

concept_class_id

string

Concept class identifier

standard_concept

string|null

Standard concept flag (S, C, or null)

level

integer

Distance from the source concept in hierarchy

total_count

integer

Total number of results

error

string

Error message if the query failed

meta

object

required

Response metadata

Show meta

request_id

string

Unique request identifier

timestamp

string

ISO 8601 timestamp

vocab_release

string

Vocabulary release version used

curl -X POST "https://api.omophub.com/v1/concepts/hierarchy/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "query_id": "q1",
        "concept_id": 201826,
        "operation": "ancestors",
        "params": {
          "max_levels": 5
        }
      },
      {
        "query_id": "q2",
        "concept_id": 4182210,
        "operation": "descendants",
        "params": {
          "max_levels": 3
        }
      },
      {
        "query_id": "q3",
        "concept_id": 313217,
        "operation": "hierarchy",
        "params": {
          "max_levels": 4,
          "relationship_types": ["Is a"]
        }
      }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      {
        "query_id": "q1",
        "concept_id": 201826,
        "operation": "ancestors",
        "success": true,
        "data": {
          "ancestors": [
            {
              "concept_id": 73211009,
              "concept_name": "Diabetes mellitus",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S",
              "level": 1
            },
            {
              "concept_id": 64572001,
              "concept_name": "Disease",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S",
              "level": 2
            }
          ],
          "total_count": 2
        }
      },
      {
        "query_id": "q2",
        "concept_id": 4182210,
        "operation": "descendants",
        "success": true,
        "data": {
          "descendants": [
            {
              "concept_id": 320128,
              "concept_name": "Essential hypertension",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S",
              "level": 1
            }
          ],
          "total_count": 1
        }
      },
      {
        "query_id": "q3",
        "concept_id": 313217,
        "operation": "hierarchy",
        "success": true,
        "data": {
          "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
            }
          ],
          "descendants": [],
          "total_count": 1
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_batch_hierarchy_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.1"
  }
}

Usage Examples

Simple Batch Ancestors

Get ancestors for multiple concepts:

{
  "queries": [
    {"query_id": "q1", "concept_id": 201826, "operation": "ancestors"},
    {"query_id": "q2", "concept_id": 4182210, "operation": "ancestors"},
    {"query_id": "q3", "concept_id": 313217, "operation": "ancestors"}
  ]
}

Mixed Operations

Combine different operations in one batch:

{
  "queries": [
    {"query_id": "ancestors_query", "concept_id": 201826, "operation": "ancestors", "params": {"max_levels": 5}},
    {"query_id": "descendants_query", "concept_id": 4182210, "operation": "descendants", "params": {"max_levels": 3}},
    {"query_id": "full_hierarchy", "concept_id": 313217, "operation": "hierarchy", "params": {"max_levels": 4}}
  ]
}

With Filtering

Use vocabulary and relationship filters:

{
  "queries": [
    {
      "query_id": "filtered_query",
      "concept_id": 201826,
      "operation": "hierarchy",
      "params": {
        "max_levels": 5,
        "relationship_types": ["Is a"],
        "vocabulary_ids": ["SNOMED", "ICD10CM"]
      }
    }
  ]
}

Important Notes

Batch size limit: Maximum 100 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 matching: Use query_id to match results to your input queries
Rate limiting: Batch requests count as single requests for rate limiting purposes

Get Concept Ancestors - Single concept ancestors
Get Concept Descendants - Single concept descendants
Get Concept Hierarchy - Complete hierarchy tree

Batch Relationship Queries Get Concept Ancestors

​Overview

​Request Body

​Query Parameters

​Response

​Usage Examples

​Simple Batch Ancestors

​Mixed Operations

​With Filtering

​Important Notes

​Related Endpoints

Overview

Request Body

Query Parameters

Response

Usage Examples

Simple Batch Ancestors

Mixed Operations

With Filtering

Important Notes

Related Endpoints