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_ids": ["Maps to", "Is a"]
}
},
{
"query_id": "diabetes_related",
"concept_id": 201826,
"operation": "related",
"params": {
"page_size": 1
}
},
{
"query_id": "diabetes_traverse",
"concept_id": 201826,
"operation": "traverse",
"params": {
"max_depth": 1,
"relationship_types": ["Is a"]
}
}
]
}'
import requests
def batch_relationship_query(queries, api_key):
url = "https://api.omophub.com/v1/concepts/relationships/batch"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
data = {"queries": queries}
response = requests.post(url, json=data, headers=headers)
return response.json()
# Example: Batch query for cardiovascular conditions
queries = [
{
"query_id": "diabetes",
"concept_id": 201826,
"operation": "relationships",
"params": {
"relationship_ids": ["Maps to", "Is a"]
}
},
{
"query_id": "hypertension",
"concept_id": 4182210,
"operation": "relationships",
"params": {
"relationship_ids": ["Maps to"],
"vocabulary_ids": ["ICD10CM"]
}
},
{
"query_id": "afib",
"concept_id": 313217,
"operation": "related",
"params": {}
}
]
result = batch_relationship_query(queries, "YOUR_API_KEY")
for query_result in result['data']:
if query_result['success']:
print(f"{query_result['query_id']}: Success")
else:
print(f"{query_result['query_id']}: Error - {query_result['error']}")
import { OMOPHub } from '@omophub/omophub-node';
// Not yet exposed as a dedicated SDK method - use the typed low-level helper.
const client = new OMOPHub();
interface BatchRelResult {
query_id: string;
concept_id: number;
operation: 'relationships' | 'related' | 'traverse';
success: boolean;
data?: unknown[] | Record<string, unknown>;
error?: string;
}
const { data } = await client.post<BatchRelResult[]>(
'/concepts/relationships/batch',
{
queries: [
/* see Python example */
],
}
);
// Example usage
const queries = [
{
query_id: 'q1',
concept_id: 201826,
operation: 'relationships',
params: {
relationship_ids: ['Maps to', 'Is a'],
},
},
{
query_id: 'q2',
concept_id: 4182210,
operation: 'relationships',
params: {
relationship_ids: ['Maps to'],
vocabulary_ids: ['ICD10CM'],
},
},
{
query_id: 'q3',
concept_id: 313217,
operation: 'related',
params: {},
},
];
const result = await batchRelationshipQuery(queries);
result.data.forEach(queryResult => {
if (queryResult.success) {
console.log(`${queryResult.query_id}: Success`);
} else {
console.error(`${queryResult.query_id} failed: ${queryResult.error}`);
}
});
{
"success": true,
"data": [
{
"query_id": "diabetes_rels",
"concept_id": 201826,
"operation": "relationships",
"success": true,
"data": [
{
"concept_id_1": 201826,
"concept_id_2": 201820,
"relationship_id": "Is a",
"relationship_name": "Is a",
"reverse_relationship_id": "Subsumes",
"concept_1": {
"concept_id": 201826,
"concept_name": "Type 2 diabetes mellitus",
"concept_code": "44054006",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Disorder",
"standard_concept": "S",
"valid_start_date": "2002-01-31",
"valid_end_date": "2099-12-31",
"invalid_reason": null
},
"concept_2": {
"concept_id": 201820,
"concept_name": "Diabetes mellitus",
"concept_code": "73211009",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Disorder",
"standard_concept": "S",
"valid_start_date": "2002-01-31",
"valid_end_date": "2099-12-31",
"invalid_reason": null
},
"valid_start_date": "2002-01-31",
"valid_end_date": "2099-12-31",
"invalid_reason": null
}
]
},
{
"query_id": "diabetes_related",
"concept_id": 201826,
"operation": "related",
"success": true,
"data": [
{
"concept_id": 40483315,
"concept_name": "Brittle type 2 diabetes mellitus",
"concept_code": "445353002",
"vocabulary_id": "SNOMED",
"relationship_id": "Subsumes",
"relationship_name": "Subsumes",
"relationship_score": 0.9,
"relationship_distance": 1
}
]
},
{
"query_id": "diabetes_traverse",
"concept_id": 201826,
"operation": "traverse",
"success": true,
"data": {
"starting_concepts": [201826],
"discovered_concepts": [
{
"concept_id": 201820,
"concept_name": "Diabetes mellitus",
"vocabulary_id": "SNOMED",
"relationship_id": "traversal",
"relationship_name": "Discovered through traversal",
"relationship_score": 0.8,
"relationship_distance": 1
}
],
"relationship_paths": [],
"traversal_stats": {
"total_concepts_discovered": 1,
"max_depth_reached": 1,
"total_relationships_explored": 2,
"unique_relationship_types": ["Is a"]
}
}
}
],
"meta": {
"request_id": "req_batch_relationships_123",
"timestamp": "2024-12-22T10:00:00Z",
"vocab_release": "2025.1"
}
}
Batch Relationship Queries
Run multiple OMOP concept relationship queries in a single batched request for efficient bulk processing of mappings and vocabulary crosswalks.
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_ids": ["Maps to", "Is a"]
}
},
{
"query_id": "diabetes_related",
"concept_id": 201826,
"operation": "related",
"params": {
"page_size": 1
}
},
{
"query_id": "diabetes_traverse",
"concept_id": 201826,
"operation": "traverse",
"params": {
"max_depth": 1,
"relationship_types": ["Is a"]
}
}
]
}'
import requests
def batch_relationship_query(queries, api_key):
url = "https://api.omophub.com/v1/concepts/relationships/batch"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
data = {"queries": queries}
response = requests.post(url, json=data, headers=headers)
return response.json()
# Example: Batch query for cardiovascular conditions
queries = [
{
"query_id": "diabetes",
"concept_id": 201826,
"operation": "relationships",
"params": {
"relationship_ids": ["Maps to", "Is a"]
}
},
{
"query_id": "hypertension",
"concept_id": 4182210,
"operation": "relationships",
"params": {
"relationship_ids": ["Maps to"],
"vocabulary_ids": ["ICD10CM"]
}
},
{
"query_id": "afib",
"concept_id": 313217,
"operation": "related",
"params": {}
}
]
result = batch_relationship_query(queries, "YOUR_API_KEY")
for query_result in result['data']:
if query_result['success']:
print(f"{query_result['query_id']}: Success")
else:
print(f"{query_result['query_id']}: Error - {query_result['error']}")
import { OMOPHub } from '@omophub/omophub-node';
// Not yet exposed as a dedicated SDK method - use the typed low-level helper.
const client = new OMOPHub();
interface BatchRelResult {
query_id: string;
concept_id: number;
operation: 'relationships' | 'related' | 'traverse';
success: boolean;
data?: unknown[] | Record<string, unknown>;
error?: string;
}
const { data } = await client.post<BatchRelResult[]>(
'/concepts/relationships/batch',
{
queries: [
/* see Python example */
],
}
);
// Example usage
const queries = [
{
query_id: 'q1',
concept_id: 201826,
operation: 'relationships',
params: {
relationship_ids: ['Maps to', 'Is a'],
},
},
{
query_id: 'q2',
concept_id: 4182210,
operation: 'relationships',
params: {
relationship_ids: ['Maps to'],
vocabulary_ids: ['ICD10CM'],
},
},
{
query_id: 'q3',
concept_id: 313217,
operation: 'related',
params: {},
},
];
const result = await batchRelationshipQuery(queries);
result.data.forEach(queryResult => {
if (queryResult.success) {
console.log(`${queryResult.query_id}: Success`);
} else {
console.error(`${queryResult.query_id} failed: ${queryResult.error}`);
}
});
{
"success": true,
"data": [
{
"query_id": "diabetes_rels",
"concept_id": 201826,
"operation": "relationships",
"success": true,
"data": [
{
"concept_id_1": 201826,
"concept_id_2": 201820,
"relationship_id": "Is a",
"relationship_name": "Is a",
"reverse_relationship_id": "Subsumes",
"concept_1": {
"concept_id": 201826,
"concept_name": "Type 2 diabetes mellitus",
"concept_code": "44054006",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Disorder",
"standard_concept": "S",
"valid_start_date": "2002-01-31",
"valid_end_date": "2099-12-31",
"invalid_reason": null
},
"concept_2": {
"concept_id": 201820,
"concept_name": "Diabetes mellitus",
"concept_code": "73211009",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Disorder",
"standard_concept": "S",
"valid_start_date": "2002-01-31",
"valid_end_date": "2099-12-31",
"invalid_reason": null
},
"valid_start_date": "2002-01-31",
"valid_end_date": "2099-12-31",
"invalid_reason": null
}
]
},
{
"query_id": "diabetes_related",
"concept_id": 201826,
"operation": "related",
"success": true,
"data": [
{
"concept_id": 40483315,
"concept_name": "Brittle type 2 diabetes mellitus",
"concept_code": "445353002",
"vocabulary_id": "SNOMED",
"relationship_id": "Subsumes",
"relationship_name": "Subsumes",
"relationship_score": 0.9,
"relationship_distance": 1
}
]
},
{
"query_id": "diabetes_traverse",
"concept_id": 201826,
"operation": "traverse",
"success": true,
"data": {
"starting_concepts": [201826],
"discovered_concepts": [
{
"concept_id": 201820,
"concept_name": "Diabetes mellitus",
"vocabulary_id": "SNOMED",
"relationship_id": "traversal",
"relationship_name": "Discovered through traversal",
"relationship_score": 0.8,
"relationship_distance": 1
}
],
"relationship_paths": [],
"traversal_stats": {
"total_concepts_discovered": 1,
"max_depth_reached": 1,
"total_relationships_explored": 2,
"unique_relationship_types": ["Is a"]
}
}
}
],
"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
array
required
Array of relationship query requests (1-100 queries)
Show queries
Show queries
string
required
Unique identifier for this query (used to match results)
integer
required
The OMOP concept ID to query relationships for
string
required
Type of relationship query. The selected value determines the allowed
fields in
params.object
Optional parameters for the query
Show params
Show params
string[]
Canonical relationship ID filter for
operation: "relationships"
(for example, ["Maps to", "Is a"]).string[]
deprecated
Relationship filter for
related and traverse. For
relationships, this remains a deprecated compatibility alias for
relationship_ids; do not send both names.string[]
Related-concept vocabulary filter for
relationships only.string[]
Related-concept domain filter for
relationships only.boolean
Include invalid relationships and concepts for
relationships only.
The default is false.boolean
Return only standard-concept relationships for
relationships only.
The default is false.boolean
Include relationships where the requested concept is the target, for
relationships only. The default is false.integer
Maximum results for
related only. The default is 50.number
Minimum score for
related or traverse. Defaults to 0.1 for
related and 0 for traverse.integer
Maximum traversal depth for
traverse only. The default is 3.Operation-specific parameters
| Operation | Accepted params fields |
|---|---|
relationships | relationship_ids, deprecated relationship_types alias, include_invalid, vocabulary_ids, domain_ids, standard_only, include_reverse |
related | relationship_types, page_size, min_score |
traverse | relationship_types, max_depth, min_score |
include_paths and breadth_first are not
accepted by the batch endpoint because its traversal implementation does not
consume them.
Query Parameters
string
Specific vocabulary release version (e.g., “2025.1”)
Response
boolean
required
Indicates whether the overall batch request was successful
array
required
Array of query results matching the input order
Show data
Show data
string
The query identifier from the request
integer
The concept ID that was queried
string
The operation that was performed
boolean
Whether this individual query succeeded
array | object
Result data if the query succeeded. Its shape depends on
operation:
relationships and related return arrays; traverse returns an object
with starting_concepts, discovered_concepts, relationship_paths, and
traversal_stats.integer
Requested concept ID in a
relationships result.integer
Related concept ID in a
relationships result.string
Forward OMOP relationship identifier.
string
Human-readable forward relationship name.
string
Reverse OMOP relationship identifier.
string
Relationship validity start date.
string
Relationship validity end date.
string | null
Relationship invalidity marker, or null when valid.
object
Full requested-concept record for a
relationships result.integer
string
string
string
string
string
string
string | null
string
string
string | null
object
Full related-concept record for a
relationships result.integer
string
string
string
string
string
string
string | null
string
string
string | null
integer
Related concept ID in a
related result.string
string
string
number
integer
array
Starting concept IDs for a
traverse result.array
Concepts discovered by traversal.
integer
string
string
string
string
number
integer
array
Traversal paths, empty when path collection is not requested.
object
Traversal summary.
integer
integer
integer
array
string
Error message if the query failed
object
required
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_ids": ["Maps to", "Is a"]
}
},
{
"query_id": "diabetes_related",
"concept_id": 201826,
"operation": "related",
"params": {
"page_size": 1
}
},
{
"query_id": "diabetes_traverse",
"concept_id": 201826,
"operation": "traverse",
"params": {
"max_depth": 1,
"relationship_types": ["Is a"]
}
}
]
}'
import requests
def batch_relationship_query(queries, api_key):
url = "https://api.omophub.com/v1/concepts/relationships/batch"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
data = {"queries": queries}
response = requests.post(url, json=data, headers=headers)
return response.json()
# Example: Batch query for cardiovascular conditions
queries = [
{
"query_id": "diabetes",
"concept_id": 201826,
"operation": "relationships",
"params": {
"relationship_ids": ["Maps to", "Is a"]
}
},
{
"query_id": "hypertension",
"concept_id": 4182210,
"operation": "relationships",
"params": {
"relationship_ids": ["Maps to"],
"vocabulary_ids": ["ICD10CM"]
}
},
{
"query_id": "afib",
"concept_id": 313217,
"operation": "related",
"params": {}
}
]
result = batch_relationship_query(queries, "YOUR_API_KEY")
for query_result in result['data']:
if query_result['success']:
print(f"{query_result['query_id']}: Success")
else:
print(f"{query_result['query_id']}: Error - {query_result['error']}")
import { OMOPHub } from '@omophub/omophub-node';
// Not yet exposed as a dedicated SDK method - use the typed low-level helper.
const client = new OMOPHub();
interface BatchRelResult {
query_id: string;
concept_id: number;
operation: 'relationships' | 'related' | 'traverse';
success: boolean;
data?: unknown[] | Record<string, unknown>;
error?: string;
}
const { data } = await client.post<BatchRelResult[]>(
'/concepts/relationships/batch',
{
queries: [
/* see Python example */
],
}
);
// Example usage
const queries = [
{
query_id: 'q1',
concept_id: 201826,
operation: 'relationships',
params: {
relationship_ids: ['Maps to', 'Is a'],
},
},
{
query_id: 'q2',
concept_id: 4182210,
operation: 'relationships',
params: {
relationship_ids: ['Maps to'],
vocabulary_ids: ['ICD10CM'],
},
},
{
query_id: 'q3',
concept_id: 313217,
operation: 'related',
params: {},
},
];
const result = await batchRelationshipQuery(queries);
result.data.forEach(queryResult => {
if (queryResult.success) {
console.log(`${queryResult.query_id}: Success`);
} else {
console.error(`${queryResult.query_id} failed: ${queryResult.error}`);
}
});
{
"success": true,
"data": [
{
"query_id": "diabetes_rels",
"concept_id": 201826,
"operation": "relationships",
"success": true,
"data": [
{
"concept_id_1": 201826,
"concept_id_2": 201820,
"relationship_id": "Is a",
"relationship_name": "Is a",
"reverse_relationship_id": "Subsumes",
"concept_1": {
"concept_id": 201826,
"concept_name": "Type 2 diabetes mellitus",
"concept_code": "44054006",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Disorder",
"standard_concept": "S",
"valid_start_date": "2002-01-31",
"valid_end_date": "2099-12-31",
"invalid_reason": null
},
"concept_2": {
"concept_id": 201820,
"concept_name": "Diabetes mellitus",
"concept_code": "73211009",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Disorder",
"standard_concept": "S",
"valid_start_date": "2002-01-31",
"valid_end_date": "2099-12-31",
"invalid_reason": null
},
"valid_start_date": "2002-01-31",
"valid_end_date": "2099-12-31",
"invalid_reason": null
}
]
},
{
"query_id": "diabetes_related",
"concept_id": 201826,
"operation": "related",
"success": true,
"data": [
{
"concept_id": 40483315,
"concept_name": "Brittle type 2 diabetes mellitus",
"concept_code": "445353002",
"vocabulary_id": "SNOMED",
"relationship_id": "Subsumes",
"relationship_name": "Subsumes",
"relationship_score": 0.9,
"relationship_distance": 1
}
]
},
{
"query_id": "diabetes_traverse",
"concept_id": 201826,
"operation": "traverse",
"success": true,
"data": {
"starting_concepts": [201826],
"discovered_concepts": [
{
"concept_id": 201820,
"concept_name": "Diabetes mellitus",
"vocabulary_id": "SNOMED",
"relationship_id": "traversal",
"relationship_name": "Discovered through traversal",
"relationship_score": 0.8,
"relationship_distance": 1
}
],
"relationship_paths": [],
"traversal_stats": {
"total_concepts_discovered": 1,
"max_depth_reached": 1,
"total_relationships_explored": 2,
"unique_relationship_types": ["Is a"]
}
}
}
],
"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_ids": ["Maps to"]
}
},
{
"query_id": "hypertension_maps",
"concept_id": 4182210,
"operation": "relationships",
"params": {
"relationship_ids": ["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_ids": ["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_idto match results to your input queries - Rate limiting: Batch requests count as single requests for rate limiting purposes
Related Endpoints
- Get Concept Relationships - Single concept relationships
- Batch Hierarchy Queries - Batch hierarchy queries
- Traverse Relationships - Complex relationship traversals
Was this page helpful?