Skip to main content
curl -X POST "https://api.omophub.com/v1/concepts/relationships/batch?vocab_release=2024.1&include_concept_details=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "concept_id": 201826,
        "relationship_types": ["Maps to", "Is a"],
        "direction": "both",
        "max_results": 20
      },
      {
        "concept_id": 4182210,
        "relationship_types": ["Maps to"],
        "direction": "outbound",
        "vocabulary_ids": ["ICD10CM", "ICD9CM"]
      },
      {
        "concept_id": 313217,
        "direction": "both",
        "include_invalid": false,
        "max_results": 30
      }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      {
        "concept_id": 201826,
        "success": true,
        "concept_details": {
          "concept_name": "Type 2 diabetes mellitus",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        "relationships": [
          {
            "relationship_type": "Maps to",
            "related_concept": {
              "concept_id": 44054006,
              "concept_name": "Diabetes mellitus type 2 (disorder)",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S",
              "concept_code": "44054006"
            },
            "direction": "outbound",
            "valid_start_date": "2002-01-31",
            "valid_end_date": "2099-12-31"
          },
          {
            "relationship_type": "Is a",
            "related_concept": {
              "concept_id": 73211009,
              "concept_name": "Diabetes mellitus",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S",
              "concept_code": "73211009"
            },
            "direction": "outbound",
            "valid_start_date": "2002-01-31",
            "valid_end_date": "2099-12-31"
          },
          {
            "relationship_type": "Maps to",
            "related_concept": {
              "concept_id": 435216,
              "concept_name": "Type 2 diabetes mellitus",
              "vocabulary_id": "ICD10CM",
              "domain_id": "Condition",
              "concept_class_id": "ICD10 code",
              "standard_concept": "S",
              "concept_code": "E11"
            },
            "direction": "outbound",
            "valid_start_date": "2016-10-01",
            "valid_end_date": "2099-12-31"
          }
        ],
        "summary": {
          "total_relationships": 15,
          "outbound_count": 8,
          "inbound_count": 7,
          "relationship_types": ["Maps to", "Is a", "Subsumes"],
          "connected_vocabularies": ["SNOMED", "ICD10CM"],
          "has_standard_mappings": true,
          "results_truncated": false
        }
      },
      {
        "concept_id": 4182210,
        "success": true,
        "concept_details": {
          "concept_name": "Hypertensive disorder",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        "relationships": [
          {
            "relationship_type": "Maps to",
            "related_concept": {
              "concept_id": 312327,
              "concept_name": "Essential hypertension",
              "vocabulary_id": "ICD10CM",
              "domain_id": "Condition",
              "concept_class_id": "4-char billing code",
              "standard_concept": null,
              "concept_code": "I10"
            },
            "direction": "outbound",
            "valid_start_date": "2015-10-01",
            "valid_end_date": "2099-12-31"
          }
        ],
        "summary": {
          "total_relationships": 8,
          "outbound_count": 5,
          "inbound_count": 3,
          "relationship_types": ["Maps to", "Is a"],
          "connected_vocabularies": ["SNOMED", "ICD10CM", "ICD9CM"],
          "has_standard_mappings": true,
          "results_truncated": false
        }
      }
    ],
    "batch_summary": {
      "total_queries": 2,
      "successful_queries": 2,
      "failed_queries": 0,
      "total_relationships_found": 23,
      "unique_concepts_involved": 18,
      "processing_time_ms": 145,
      "cache_hit_rate": 65.5
    }
  },
  "meta": {
    "request_id": "req_batch_relationships_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2",
    "pagination": {
      "total_items": 2,
      "page": 1,
      "page_size": 50
    }
  }
}

​
Overview

This endpoint allows you to retrieve relationship information for multiple concepts in a single API call. It’s optimized for bulk operations and provides significant performance benefits when working with large sets of concepts.

​
Request Body

​
queries
array
required
Array of relationship query requests

​
Query Parameters

​
vocab_release
string
Specific vocabulary release version (e.g., “2024.1”)
​
include_concept_details
boolean
default:"true"
Include full concept details in responses
​
page
integer
default:"1"
Page number for paginated results
Range: Minimum value is 1. If page exceeds total pages, returns empty results with pagination metadata
​
page_size
integer
default:"50"
Number of batch query results per page
Range: 1-500. Maximum page size is 500 for performance reasons

​
Response

​
success
boolean
required
Indicates whether the overall batch request was successful
​
meta
object
Response metadata and API information
​
results
array
required
Array of relationship 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/relationships/batch?vocab_release=2024.1&include_concept_details=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "concept_id": 201826,
        "relationship_types": ["Maps to", "Is a"],
        "direction": "both",
        "max_results": 20
      },
      {
        "concept_id": 4182210,
        "relationship_types": ["Maps to"],
        "direction": "outbound",
        "vocabulary_ids": ["ICD10CM", "ICD9CM"]
      },
      {
        "concept_id": 313217,
        "direction": "both",
        "include_invalid": false,
        "max_results": 30
      }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      {
        "concept_id": 201826,
        "success": true,
        "concept_details": {
          "concept_name": "Type 2 diabetes mellitus",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        "relationships": [
          {
            "relationship_type": "Maps to",
            "related_concept": {
              "concept_id": 44054006,
              "concept_name": "Diabetes mellitus type 2 (disorder)",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S",
              "concept_code": "44054006"
            },
            "direction": "outbound",
            "valid_start_date": "2002-01-31",
            "valid_end_date": "2099-12-31"
          },
          {
            "relationship_type": "Is a",
            "related_concept": {
              "concept_id": 73211009,
              "concept_name": "Diabetes mellitus",
              "vocabulary_id": "SNOMED",
              "domain_id": "Condition",
              "concept_class_id": "Clinical Finding",
              "standard_concept": "S",
              "concept_code": "73211009"
            },
            "direction": "outbound",
            "valid_start_date": "2002-01-31",
            "valid_end_date": "2099-12-31"
          },
          {
            "relationship_type": "Maps to",
            "related_concept": {
              "concept_id": 435216,
              "concept_name": "Type 2 diabetes mellitus",
              "vocabulary_id": "ICD10CM",
              "domain_id": "Condition",
              "concept_class_id": "ICD10 code",
              "standard_concept": "S",
              "concept_code": "E11"
            },
            "direction": "outbound",
            "valid_start_date": "2016-10-01",
            "valid_end_date": "2099-12-31"
          }
        ],
        "summary": {
          "total_relationships": 15,
          "outbound_count": 8,
          "inbound_count": 7,
          "relationship_types": ["Maps to", "Is a", "Subsumes"],
          "connected_vocabularies": ["SNOMED", "ICD10CM"],
          "has_standard_mappings": true,
          "results_truncated": false
        }
      },
      {
        "concept_id": 4182210,
        "success": true,
        "concept_details": {
          "concept_name": "Hypertensive disorder",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        "relationships": [
          {
            "relationship_type": "Maps to",
            "related_concept": {
              "concept_id": 312327,
              "concept_name": "Essential hypertension",
              "vocabulary_id": "ICD10CM",
              "domain_id": "Condition",
              "concept_class_id": "4-char billing code",
              "standard_concept": null,
              "concept_code": "I10"
            },
            "direction": "outbound",
            "valid_start_date": "2015-10-01",
            "valid_end_date": "2099-12-31"
          }
        ],
        "summary": {
          "total_relationships": 8,
          "outbound_count": 5,
          "inbound_count": 3,
          "relationship_types": ["Maps to", "Is a"],
          "connected_vocabularies": ["SNOMED", "ICD10CM", "ICD9CM"],
          "has_standard_mappings": true,
          "results_truncated": false
        }
      }
    ],
    "batch_summary": {
      "total_queries": 2,
      "successful_queries": 2,
      "failed_queries": 0,
      "total_relationships_found": 23,
      "unique_concepts_involved": 18,
      "processing_time_ms": 145,
      "cache_hit_rate": 65.5
    }
  },
  "meta": {
    "request_id": "req_batch_relationships_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2",
    "pagination": {
      "total_items": 2,
      "page": 1,
      "page_size": 50
    }
  }
}

​
Usage Examples

​
Basic Batch Query

Get relationships for multiple concepts: 
{
  "queries": [
    {"concept_id": 201826, "max_results": 20},
    {"concept_id": 4182210, "max_results": 20},
    {"concept_id": 313217, "max_results": 20}
  ]
}

​
Filtered by Relationship Type

Get only mapping relationships: 
{
  "queries": [
    {
      "concept_id": 201826,
      "relationship_types": ["Maps to"],
      "direction": "outbound"
    },
    {
      "concept_id": 4182210,
      "relationship_types": ["Maps to"],
      "vocabulary_ids": ["ICD10CM"]
    }
  ]
}

​
Mixed Query Configuration

Different configurations per concept: 
{
  "queries": [
    {
      "concept_id": 201826,
      "relationship_types": ["Is a", "Subsumes"],
      "direction": "both",
      "max_results": 30
    },
    {
      "concept_id": 4182210,
      "relationship_types": ["Maps to"],
      "vocabulary_ids": ["ICD10CM", "ICD9CM"],
      "max_results": 10
    }
  ]
}

​
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 ordering: Results are returned in the same order as input queries
  • Cache benefits: Frequently accessed concepts benefit from caching, improving response times
  • Rate limiting: Batch requests count as single requests for rate limiting purposes
⌘I