Skip to main content
GET
https://api.omophub.com
/
v1
/
concepts
/
{conceptId}
/
relations
curl -X GET "https://api.omophub.com/v1/concepts/201826/relations?relationship_types=Maps%20to,Is%20a" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "concept": {
      "concept_id": 201826,
      "concept_name": "Type 2 diabetes mellitus",
      "vocabulary_id": "SNOMED"
    },
    "relations": [
      {
        "relationship_type": "Maps to",
        "related_concept": {
          "concept_id": 1567956,
          "concept_name": "Type 2 diabetes mellitus",
          "vocabulary_id": "ICD10CM",
          "domain_id": "Condition",
          "concept_class_id": "4-char billing code",
          "standard_concept": null,
          "concept_code": "E11.9"
        },
        "direction": "inbound",
        "valid_start_date": "2015-10-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "relationship_type": "Is a",
        "related_concept": {
          "concept_id": 201820,
          "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",
        "invalid_reason": null
      },
      {
        "relationship_type": "Has finding site",
        "related_concept": {
          "concept_id": 113331007,
          "concept_name": "Endocrine system structure",
          "vocabulary_id": "SNOMED",
          "domain_id": "Spec Anatomic Site",
          "concept_class_id": "Body Structure",
          "standard_concept": "S",
          "concept_code": "113331007"
        },
        "direction": "outbound",
        "valid_start_date": "2002-01-31",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "relationship_type": "Mapped from",
        "related_concept": {
          "concept_id": 44835411,
          "concept_name": "Type 2 diabetes mellitus",
          "vocabulary_id": "ICD9CM",
          "domain_id": "Condition",
          "concept_class_id": "3-dig billing code",
          "standard_concept": null,
          "concept_code": "250.00"
        },
        "direction": "inbound",
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2014-09-30",
        "invalid_reason": null
      }
    ],
    "summary": {
      "total_relations": 15,
      "outbound_count": 8,
      "inbound_count": 7,
      "relationship_types": ["Maps to", "Is a", "Has finding site", "May be a", "Mapped from"],
      "vocabularies_involved": ["SNOMED", "ICD10CM", "ICD9CM"]
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 15,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    },
    "request_id": "req_relations_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

​
Overview

This endpoint returns all direct relationships for a given concept, showing how it connects to other concepts in the medical terminology network. This includes both inbound and outbound relationships with their relationship types.

​
Path Parameters

​
conceptId
integer
required
The unique OMOP concept ID to get relations for

​
Query Parameters

​
relationship_types
string
Comma-separated list of relationship types to filter by (e.g., “Maps to”, “Is a”)
​
vocabulary_ids
string
Comma-separated list of vocabulary IDs to filter related concepts
​
include_reverse
boolean
default:"true"
Include reverse relationships (concepts that relate to this concept)
​
include_invalid
boolean
default:"false"
Include relationships to invalid/deprecated concepts
​
vocab_release
string
Specific vocabulary release version (e.g., “2024.1”)
​
page
integer
default:"1"
Page number for pagination (1-based)
​
page_size
integer
default:"20"
Number of relationships per page

​
Response

​
concept
object
required
The source concept details
​
relations
array
required
Array of direct relationships
​
summary
object
required
Summary statistics for relationships
​
success
boolean
required
Indicates if the request was successful
​
meta
object
required
Response metadata including pagination and request information
curl -X GET "https://api.omophub.com/v1/concepts/201826/relations?relationship_types=Maps%20to,Is%20a" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "concept": {
      "concept_id": 201826,
      "concept_name": "Type 2 diabetes mellitus",
      "vocabulary_id": "SNOMED"
    },
    "relations": [
      {
        "relationship_type": "Maps to",
        "related_concept": {
          "concept_id": 1567956,
          "concept_name": "Type 2 diabetes mellitus",
          "vocabulary_id": "ICD10CM",
          "domain_id": "Condition",
          "concept_class_id": "4-char billing code",
          "standard_concept": null,
          "concept_code": "E11.9"
        },
        "direction": "inbound",
        "valid_start_date": "2015-10-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "relationship_type": "Is a",
        "related_concept": {
          "concept_id": 201820,
          "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",
        "invalid_reason": null
      },
      {
        "relationship_type": "Has finding site",
        "related_concept": {
          "concept_id": 113331007,
          "concept_name": "Endocrine system structure",
          "vocabulary_id": "SNOMED",
          "domain_id": "Spec Anatomic Site",
          "concept_class_id": "Body Structure",
          "standard_concept": "S",
          "concept_code": "113331007"
        },
        "direction": "outbound",
        "valid_start_date": "2002-01-31",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "relationship_type": "Mapped from",
        "related_concept": {
          "concept_id": 44835411,
          "concept_name": "Type 2 diabetes mellitus",
          "vocabulary_id": "ICD9CM",
          "domain_id": "Condition",
          "concept_class_id": "3-dig billing code",
          "standard_concept": null,
          "concept_code": "250.00"
        },
        "direction": "inbound",
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2014-09-30",
        "invalid_reason": null
      }
    ],
    "summary": {
      "total_relations": 15,
      "outbound_count": 8,
      "inbound_count": 7,
      "relationship_types": ["Maps to", "Is a", "Has finding site", "May be a", "Mapped from"],
      "vocabularies_involved": ["SNOMED", "ICD10CM", "ICD9CM"]
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 15,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    },
    "request_id": "req_relations_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

​
Get All Relations

Retrieve all relationships for a concept: 
curl -X GET "https://api.omophub.com/v1/concepts/201826/relations" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Filter by Relationship Type

Get only mapping relationships: 
curl -X GET "https://api.omophub.com/v1/concepts/201826/relations?relationship_types=Maps%20to" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Cross-Vocabulary Relations

Find relationships to concepts in specific vocabularies: 
curl -X GET "https://api.omophub.com/v1/concepts/201826/relations?vocabulary_ids=ICD10CM,ICD9CM" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Important Notes

  • Relationship direction indicates whether this concept relates to another (outbound) or vice versa (inbound)
  • Standard concepts are preferred for analysis and should be prioritized
  • Invalid relationships are excluded by default but can be included for historical analysis
  • Pagination is available for concepts with many relationships
  • Performance may vary based on concept complexity and filter criteria