List Relationships for a Concept

curl -G "https://api.omophub.com/v1/concepts/201826/relationships" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "relationship_ids=Is a,Maps to" \
  --data-urlencode "page_size=50"

import requests

concept_id = 201826
url = f"https://api.omophub.com/v1/concepts/{concept_id}/relationships"
params = {
    "relationship_ids": "Is a,Maps to",
    "vocabulary_ids": "SNOMED",
    "page_size": 50
}

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(url, params=params, headers=headers)
data = response.json()

print(f"Total relationships: {data['meta']['pagination']['total_items']}")
for rel in data['data']['relationships']:
    print(f"  {rel['relationship_id']}: {rel['concept_2']['concept_name']}")

import { OMOPHub } from '@omophub/omophub-node';

const client = new OMOPHub();
const { data, meta } = await client.relationships.get(201826, {
  relationshipIds: ['Is a', 'Maps to'],
  pageSize: 50,
});
console.log(`Found ${meta?.pagination?.total_items} relationships`);

{
  "success": true,
  "data": {
    "relationships": [
      {
        "concept_id_1": 201826,
        "concept_id_2": 73211009,
        "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",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "valid_start_date": "2002-01-31",
          "valid_end_date": "2099-12-31",
          "invalid_reason": null
        },
        "concept_2": {
          "concept_id": 73211009,
          "concept_name": "Diabetes mellitus",
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "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
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-04T10:30:00Z",
    "vocab_release": "2025.1",
    "version": "2025.1",
    "duration": 45,
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 47,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    }
  }
}

curl -G "https://api.omophub.com/v1/concepts/201826/relationships" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "relationship_ids=Is a,Maps to" \
  --data-urlencode "page_size=50"

import requests

concept_id = 201826
url = f"https://api.omophub.com/v1/concepts/{concept_id}/relationships"
params = {
    "relationship_ids": "Is a,Maps to",
    "vocabulary_ids": "SNOMED",
    "page_size": 50
}

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(url, params=params, headers=headers)
data = response.json()

print(f"Total relationships: {data['meta']['pagination']['total_items']}")
for rel in data['data']['relationships']:
    print(f"  {rel['relationship_id']}: {rel['concept_2']['concept_name']}")

import { OMOPHub } from '@omophub/omophub-node';

const client = new OMOPHub();
const { data, meta } = await client.relationships.get(201826, {
  relationshipIds: ['Is a', 'Maps to'],
  pageSize: 50,
});
console.log(`Found ${meta?.pagination?.total_items} relationships`);

{
  "success": true,
  "data": {
    "relationships": [
      {
        "concept_id_1": 201826,
        "concept_id_2": 73211009,
        "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",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "valid_start_date": "2002-01-31",
          "valid_end_date": "2099-12-31",
          "invalid_reason": null
        },
        "concept_2": {
          "concept_id": 73211009,
          "concept_name": "Diabetes mellitus",
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "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
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-04T10:30:00Z",
    "vocab_release": "2025.1",
    "version": "2025.1",
    "duration": 45,
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 47,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    }
  }
}

This endpoint provides relationship information for a concept, showing how it connects to other concepts through various relationship types such as “Is a”, “Part of”, “Has ingredient”, and others in medical vocabularies.

Path Parameters

concept_id

integer

required

The unique identifier of the concept to retrieve relationships for
Example: 201826 (Type 2 diabetes mellitus)

Query Parameters

relationship_ids

string

Comma-separated list of relationship IDs to filter by
Example: Is a,Maps to,Has finding site

vocabulary_ids

string

Filter relationships to specific vocabularies
Example: SNOMED,ICD10CM,RxNorm

domain_ids

string

Filter related concepts to specific domains
Example: Condition,Drug,Procedure

standard_only

boolean

default:"false"

Only return relationships to standard concepts

include_invalid

boolean

default:"true"

Include relationships to deprecated/invalid concepts

include_reverse

boolean

default:"false"

Include reverse relationships (where this concept is concept_id_2)

page

integer

default:"1"

Page number for pagination (1-based)

page_size

integer

default:"100"

Number of relationships to return per page (max 1000)

vocab_release

string

Specific vocabulary release version
Example: 2025.1

Response

relationships

array

Array of relationship objects

Show Relationship Object

concept_id_1

integer

Source concept ID (the concept you queried)

concept_id_2

integer

Target concept ID (the related concept)

relationship_id

string

Relationship type identifier (e.g., “Is a”, “Maps to”)

relationship_name

string

Display name of the relationship

reverse_relationship_id

string

Reverse relationship identifier (e.g., “Subsumes” for “Is a”)

concept_1

object

Full details of the source concept

Show Concept Object

concept_id

integer

Concept identifier

concept_name

string

Concept name

concept_code

string

Original vocabulary code

vocabulary_id

string

Vocabulary identifier

vocabulary_name

string

Vocabulary display name

domain_id

string

Domain classification

concept_class_id

string

Concept class

standard_concept

string

Standard concept flag (S, C, or null)

valid_start_date

string

Validity start date

valid_end_date

string

Validity end date

invalid_reason

string

Reason if invalid (null if valid)

concept_2

object

Full details of the target concept (same structure as concept_1)

valid_start_date

string

Date when relationship became valid

valid_end_date

string

Date when relationship becomes invalid

invalid_reason

string

Reason if relationship is invalid (null if valid)

meta

object

Response metadata including pagination

Show Metadata Object

pagination

object

page

integer

Current page number

page_size

integer

Items per page

total_items

integer

Total relationships

total_pages

integer

Total number of pages

has_next

boolean

Whether next page exists

has_previous

boolean

Whether previous page exists

request_id

string

Unique request identifier

timestamp

string

Request timestamp

vocab_release

string

Vocabulary release version used

curl -G "https://api.omophub.com/v1/concepts/201826/relationships" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "relationship_ids=Is a,Maps to" \
  --data-urlencode "page_size=50"

import requests

concept_id = 201826
url = f"https://api.omophub.com/v1/concepts/{concept_id}/relationships"
params = {
    "relationship_ids": "Is a,Maps to",
    "vocabulary_ids": "SNOMED",
    "page_size": 50
}

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(url, params=params, headers=headers)
data = response.json()

print(f"Total relationships: {data['meta']['pagination']['total_items']}")
for rel in data['data']['relationships']:
    print(f"  {rel['relationship_id']}: {rel['concept_2']['concept_name']}")

import { OMOPHub } from '@omophub/omophub-node';

const client = new OMOPHub();
const { data, meta } = await client.relationships.get(201826, {
  relationshipIds: ['Is a', 'Maps to'],
  pageSize: 50,
});
console.log(`Found ${meta?.pagination?.total_items} relationships`);

{
  "success": true,
  "data": {
    "relationships": [
      {
        "concept_id_1": 201826,
        "concept_id_2": 73211009,
        "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",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "valid_start_date": "2002-01-31",
          "valid_end_date": "2099-12-31",
          "invalid_reason": null
        },
        "concept_2": {
          "concept_id": 73211009,
          "concept_name": "Diabetes mellitus",
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "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
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-04T10:30:00Z",
    "vocab_release": "2025.1",
    "version": "2025.1",
    "duration": 45,
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 47,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    }
  }
}

Usage Examples

All Relationships

Get all relationships for a concept:

curl "https://api.omophub.com/v1/concepts/201826/relationships" \
  -H "Authorization: Bearer YOUR_API_KEY"

Hierarchical Relationships Only

Retrieve only “Is a” relationships:

curl "https://api.omophub.com/v1/concepts/201826/relationships?relationship_ids=Is%20a" \
  -H "Authorization: Bearer YOUR_API_KEY"

Cross-Vocabulary Mappings

Find mappings to ICD-10:

curl "https://api.omophub.com/v1/concepts/201826/relationships?relationship_ids=Maps%20to&vocabulary_ids=ICD10CM" \
  -H "Authorization: Bearer YOUR_API_KEY"

Including Reverse Relationships

Include relationships where this concept is the target:

curl "https://api.omophub.com/v1/concepts/201826/relationships?include_reverse=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Relationship Types - Available relationship types
Get Concept Ancestors - Hierarchical parent relationships
Get Concept Descendants - Hierarchical child relationships
Get Concept Mappings - Cross-vocabulary mappings

Notes

Relationships are bidirectional in the database; use include_reverse=true to see both directions
Standard concepts are not filtered by default; use standard_only=true to filter
Large concepts may have hundreds of relationships - use pagination appropriately
The response includes full concept details for both source and target concepts

Get Relationship Types Get Domains

API Reference

Search

Concepts

Concept Hierarchy

Mappings

FHIR Resolver

Relationships

Domains & Classifications

Vocabularies

List Relationships for a Concept

Path Parameters

Query Parameters

Response

Usage Examples

All Relationships

Hierarchical Relationships Only

Cross-Vocabulary Mappings

Including Reverse Relationships

Notes

​Path Parameters

​Query Parameters

​Response

​Usage Examples

​All Relationships

​Hierarchical Relationships Only

​Cross-Vocabulary Mappings

​Including Reverse Relationships

​Related Endpoints

​Notes

Path Parameters

Query Parameters

Response

Usage Examples

All Relationships

Hierarchical Relationships Only

Cross-Vocabulary Mappings

Including Reverse Relationships

Related Endpoints

Notes