Skip to main content
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)

​
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
​
meta
object
required
Response metadata
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