Batch Relationship Queries

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
    }
  }
}

POST

https://api.omophub.com

concepts

relationships

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
    }
  }
}

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

Show queries

concept_id

integer

required

The OMOP concept ID to get relationships for

relationship_types

array

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

direction

string

default:"both"

Relationship direction: “outbound”, “inbound”, or “both”

vocabulary_ids

array

Array of vocabulary IDs to filter related concepts

include_invalid

boolean

default:"false"

Include relationships to invalid/deprecated concepts

max_results

integer

default:"50"

Maximum number of relationships to return for this concept

include_summary

boolean

default:"true"

Include summary statistics for this concept’s relationships

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

Show meta

request_id

string

Unique request identifier for tracking

timestamp

string

ISO 8601 timestamp of the response

pagination

object

Pagination information for batch query results

Show pagination

total_items

integer

Total number of queries in the batch (same as batch_summary.total_queries)

page

integer

Current page number (matches page query parameter)

page_size

integer

Number of batch queries per page (matches page_size query parameter)

results

array

required

Array of relationship query results matching the input order

Show results

concept_id

integer

The concept ID that was queried

success

boolean

Whether this individual query succeeded

error

string

Error message if the query failed

concept_details

object

Source concept information (when include_concept_details=true)

Show concept_details

concept_name

string

Source concept name

vocabulary_id

string

Source vocabulary

domain_id

string

Source domain

concept_class_id

string

Source concept class

standard_concept

string

Standard concept flag (“S” for standard, “C” for classification, null for non-standard)

relationships

array

Array of relationships for this concept

Show relationships

relationship_type

string

Type of relationship (e.g., “Maps to”, “Is a”)

The concept that this concept is related to

Show related_concept

concept_id

integer

Related concept ID

concept_name

string

Related concept name

vocabulary_id

string

Related concept vocabulary

domain_id

string

Related concept domain

concept_class_id

string

Related concept class

standard_concept

string

Standard concept flag (“S” for standard, “C” for classification, null for non-standard)

concept_code

string

Related concept code

direction

string

Relationship direction: “outbound” (from this concept) or “inbound” (to this concept)

valid_start_date

string

When this relationship became valid (ISO date)

valid_end_date

string

When this relationship expires (ISO date)

summary

object

Summary statistics (when include_summary=true)

Show summary

total_relationships

integer

Total number of relationships

outbound_count

integer

Number of outbound relationships

inbound_count

integer

Number of inbound relationships

relationship_types

array

Array of unique relationship types

connected_vocabularies

array

Array of vocabularies with related concepts

has_standard_mappings

boolean

Whether concept has mappings to standard concepts

results_truncated

boolean

Whether results were limited by max_results

batch_summary

object

required

Summary statistics for the entire batch

Show batch_summary

total_queries

integer

Total number of queries requested

successful_queries

integer

Number of successful queries

failed_queries

integer

Number of failed queries

total_relationships_found

integer

Total relationships across all queries

unique_concepts_involved

integer

Number of unique concepts in all results

processing_time_ms

integer

Total processing time for batch

cache_hit_rate

number

Percentage of queries served from cache

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

Get Concept Relationships - Single concept relationships
Traverse Relationships - Complex relationship traversals
Get Relationship Options - Available relationship types

Traverse Relationships Get Related Concepts

⌘I

API Reference

Concepts

Concept Hierarchy

Search

Search (Coming Soon)

Relationships

Domains & Classifications

Mappings

Vocabularies

Overview

Request Body

Query Parameters

Response

Usage Examples

Basic Batch Query

Filtered by Relationship Type

Mixed Query Configuration

Important Notes

API Reference

Concepts

Concept Hierarchy

Search

Search (Coming Soon)

Relationships

Domains & Classifications

Mappings

Vocabularies

​Overview

​Request Body

​Query Parameters

​Response

​Usage Examples

​Basic Batch Query

​Filtered by Relationship Type

​Mixed Query Configuration

​Important Notes

​Related Endpoints

Overview

Request Body

Query Parameters

Response

Usage Examples

Basic Batch Query

Filtered by Relationship Type

Mixed Query Configuration

Important Notes

Related Endpoints