Batch Relationship Queries

curl -X POST "https://api.omophub.com/v1/concepts/relationships/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "query_id": "diabetes_rels",
        "concept_id": 201826,
        "operation": "relationships",
        "params": {
          "relationship_types": ["Maps to", "Is a"]
        }
      },
      {
        "query_id": "hypertension_rels",
        "concept_id": 4182210,
        "operation": "relationships",
        "params": {
          "relationship_types": ["Maps to"],
          "vocabulary_ids": ["ICD10CM", "ICD9CM"]
        }
      },
      {
        "query_id": "afib_related",
        "concept_id": 313217,
        "operation": "related",
        "params": {
          "include_invalid": false
        }
      }
    ]
  }'

{
  "success": true,
  "data": [
    {
      "query_id": "diabetes_rels",
      "concept_id": 201826,
      "operation": "relationships",
      "success": true,
      "data": {
        "relationships": [
          {
            "relationship_id": "Maps to",
            "concept_id_2": 44054006,
            "concept_name": "Diabetes mellitus type 2",
            "vocabulary_id": "SNOMED"
          },
          {
            "relationship_id": "Is a",
            "concept_id_2": 73211009,
            "concept_name": "Diabetes mellitus",
            "vocabulary_id": "SNOMED"
          }
        ]
      }
    },
    {
      "query_id": "hypertension_rels",
      "concept_id": 4182210,
      "operation": "relationships",
      "success": true,
      "data": {
        "relationships": [
          {
            "relationship_id": "Maps to",
            "concept_id_2": 312327,
            "concept_name": "Essential hypertension",
            "vocabulary_id": "ICD10CM"
          }
        ]
      }
    },
    {
      "query_id": "afib_related",
      "concept_id": 313217,
      "operation": "related",
      "success": true,
      "data": {
        "related_concepts": [
          {
            "concept_id": 49436004,
            "concept_name": "Atrial fibrillation and flutter",
            "vocabulary_id": "SNOMED"
          }
        ]
      }
    }
  ],
  "meta": {
    "request_id": "req_batch_relationships_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.1"
  }
}

curl -X POST "https://api.omophub.com/v1/concepts/relationships/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "query_id": "diabetes_rels",
        "concept_id": 201826,
        "operation": "relationships",
        "params": {
          "relationship_types": ["Maps to", "Is a"]
        }
      },
      {
        "query_id": "hypertension_rels",
        "concept_id": 4182210,
        "operation": "relationships",
        "params": {
          "relationship_types": ["Maps to"],
          "vocabulary_ids": ["ICD10CM", "ICD9CM"]
        }
      },
      {
        "query_id": "afib_related",
        "concept_id": 313217,
        "operation": "related",
        "params": {
          "include_invalid": false
        }
      }
    ]
  }'

{
  "success": true,
  "data": [
    {
      "query_id": "diabetes_rels",
      "concept_id": 201826,
      "operation": "relationships",
      "success": true,
      "data": {
        "relationships": [
          {
            "relationship_id": "Maps to",
            "concept_id_2": 44054006,
            "concept_name": "Diabetes mellitus type 2",
            "vocabulary_id": "SNOMED"
          },
          {
            "relationship_id": "Is a",
            "concept_id_2": 73211009,
            "concept_name": "Diabetes mellitus",
            "vocabulary_id": "SNOMED"
          }
        ]
      }
    },
    {
      "query_id": "hypertension_rels",
      "concept_id": 4182210,
      "operation": "relationships",
      "success": true,
      "data": {
        "relationships": [
          {
            "relationship_id": "Maps to",
            "concept_id_2": 312327,
            "concept_name": "Essential hypertension",
            "vocabulary_id": "ICD10CM"
          }
        ]
      }
    },
    {
      "query_id": "afib_related",
      "concept_id": 313217,
      "operation": "related",
      "success": true,
      "data": {
        "related_concepts": [
          {
            "concept_id": 49436004,
            "concept_name": "Atrial fibrillation and flutter",
            "vocabulary_id": "SNOMED"
          }
        ]
      }
    }
  ],
  "meta": {
    "request_id": "req_batch_relationships_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.1"
  }
}

Overview

This endpoint allows you to perform multiple relationship-related queries for multiple concepts in a single API call. It supports different operation types: relationships, related, and traverse.

Request Body

queries

array

required

Array of relationship 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 relationships for

operation

string

required

Type of relationship query. Options: relationships, related, traverse

params

object

Optional parameters for the query

Show params

relationship_types

array

Array of relationship types to filter by (e.g., [“Maps to”, “Is a”])

vocabulary_ids

array

Array of vocabulary IDs to filter related concepts

include_invalid

boolean

default:"false"

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 overall batch request was successful

data

array

required

Array of query results matching the input order

Show data

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)

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/relationships/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "query_id": "diabetes_rels",
        "concept_id": 201826,
        "operation": "relationships",
        "params": {
          "relationship_types": ["Maps to", "Is a"]
        }
      },
      {
        "query_id": "hypertension_rels",
        "concept_id": 4182210,
        "operation": "relationships",
        "params": {
          "relationship_types": ["Maps to"],
          "vocabulary_ids": ["ICD10CM", "ICD9CM"]
        }
      },
      {
        "query_id": "afib_related",
        "concept_id": 313217,
        "operation": "related",
        "params": {
          "include_invalid": false
        }
      }
    ]
  }'

{
  "success": true,
  "data": [
    {
      "query_id": "diabetes_rels",
      "concept_id": 201826,
      "operation": "relationships",
      "success": true,
      "data": {
        "relationships": [
          {
            "relationship_id": "Maps to",
            "concept_id_2": 44054006,
            "concept_name": "Diabetes mellitus type 2",
            "vocabulary_id": "SNOMED"
          },
          {
            "relationship_id": "Is a",
            "concept_id_2": 73211009,
            "concept_name": "Diabetes mellitus",
            "vocabulary_id": "SNOMED"
          }
        ]
      }
    },
    {
      "query_id": "hypertension_rels",
      "concept_id": 4182210,
      "operation": "relationships",
      "success": true,
      "data": {
        "relationships": [
          {
            "relationship_id": "Maps to",
            "concept_id_2": 312327,
            "concept_name": "Essential hypertension",
            "vocabulary_id": "ICD10CM"
          }
        ]
      }
    },
    {
      "query_id": "afib_related",
      "concept_id": 313217,
      "operation": "related",
      "success": true,
      "data": {
        "related_concepts": [
          {
            "concept_id": 49436004,
            "concept_name": "Atrial fibrillation and flutter",
            "vocabulary_id": "SNOMED"
          }
        ]
      }
    }
  ],
  "meta": {
    "request_id": "req_batch_relationships_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.1"
  }
}

Usage Examples

Basic Batch Query

Get relationships for multiple concepts:

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

Filtered by Relationship Type

Get only mapping relationships:

{
  "queries": [
    {
      "query_id": "diabetes_maps",
      "concept_id": 201826,
      "operation": "relationships",
      "params": {
        "relationship_types": ["Maps to"]
      }
    },
    {
      "query_id": "hypertension_maps",
      "concept_id": 4182210,
      "operation": "relationships",
      "params": {
        "relationship_types": ["Maps to"],
        "vocabulary_ids": ["ICD10CM"]
      }
    }
  ]
}

Mixed Operations

Combine different operations in one batch:

{
  "queries": [
    {
      "query_id": "rels_query",
      "concept_id": 201826,
      "operation": "relationships",
      "params": {
        "relationship_types": ["Is a", "Subsumes"]
      }
    },
    {
      "query_id": "related_query",
      "concept_id": 4182210,
      "operation": "related",
      "params": {}
    },
    {
      "query_id": "traverse_query",
      "concept_id": 313217,
      "operation": "traverse",
      "params": {
        "relationship_types": ["Is a"]
      }
    }
  ]
}

Important Notes

Batch size limit: Maximum 100 queries per batch request
Performance optimization: Batch processing is significantly more efficient than individual requests
Error isolation: 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 Relationships - Single concept relationships
Batch Hierarchy Queries - Batch hierarchy queries
Traverse Relationships - Complex relationship traversals

Batch Concepts Batch Hierarchy Queries

⌘I

API Reference

Search

Concepts

Concept Hierarchy

Relationships

Domains & Classifications

Vocabularies

Mappings

Overview

Request Body

Query Parameters

Response

Usage Examples

Basic Batch Query

Filtered by Relationship Type

Mixed Operations

Important Notes

API Reference

Search

Concepts

Concept Hierarchy

Relationships

Domains & Classifications

Vocabularies

Mappings

​Overview

​Request Body

​Query Parameters

​Response

​Usage Examples

​Basic Batch Query

​Filtered by Relationship Type

​Mixed Operations

​Important Notes

​Related Endpoints

Overview

Request Body

Query Parameters

Response

Usage Examples

Basic Batch Query

Filtered by Relationship Type

Mixed Operations

Important Notes

Related Endpoints