Skip to main content

​
Overview

This guide will help you make your first API call to OMOPHub in just a few minutes. By the end, you’ll be able to search medical concepts and explore healthcare vocabularies.
PrerequisitesYou’ll need:

​
Step 1: Set Up Required Libraries

Choose your preferred programming language and install the necessary HTTP libraries: 
# Python - Install requests library
pip install requests

​
Step 2: Set Up Authentication

Prepare your API key and authentication headers for making requests: 
# Python
import requests

# Set up authentication
API_KEY = "your_api_key_here"
BASE_URL = "https://api.omophub.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}
Never hardcode your API key in your source code. Use environment variables or secure key management systems in production.

​
Step 3: Make Your First Request

Let’s search for concepts related to “hypertension”: 
# Python - Search for hypertension concepts
response = requests.get(f"{BASE_URL}/search/concepts",
    headers=headers,
    params={
        "query": "hypertension",
        "page_size": 5
    }
)

data = response.json()

# Display the results
for concept in data["data"]["concepts"]:
    print(f"ID: {concept['concept_id']}")
    print(f"Name: {concept['concept_name']}")
    print(f"Vocabulary: {concept['vocabulary_id']}")
    print(f"Domain: {concept['domain_id']}")
    print("---")

​
Step 4: Explore Concept Details

Once you have a concept ID, you can get detailed information: 
# Python - Get detailed information about a specific concept
concept_id = 320128  # Hypertension concept ID

# Get concept details
response = requests.get(f"{BASE_URL}/concepts/{concept_id}", headers=headers)
concept = response.json()["data"]

print(f"Concept: {concept['concept_name']}")
print(f"Code: {concept['concept_code']}")
print(f"Class: {concept['concept_class_id']}")
print(f"Valid dates: {concept['valid_start_date']} to {concept['valid_end_date']}")

# Get concept relationships
rel_response = requests.get(f"{BASE_URL}/concepts/{concept_id}/relationships", headers=headers)
relationships = rel_response.json()["data"]
print(f"\nFound {len(relationships)} relationships")

​
Step 5: Navigate Concept Hierarchies

Explore parent and child concepts: 
# Python - Get parent concepts (ancestors)
ancestors_response = requests.get(
    f"{BASE_URL}/concepts/320128/ancestors",
    headers=headers,
    params={"max_levels": 2}
)
ancestors = ancestors_response.json()["data"]

print("Parent concepts:")
for ancestor in ancestors:
    indent = "  " * ancestor["level_of_separation"]
    print(f"{indent}{ancestor['concept_name']}")

# Get child concepts (descendants)
descendants_response = requests.get(
    f"{BASE_URL}/concepts/320128/descendants",
    headers=headers,
    params={"max_levels": 2}
)
descendants = descendants_response.json()["data"]

print("\nChild concepts:")
for descendant in descendants:
    indent = "  " * descendant["level_of_separation"]
    print(f"{indent}{descendant['concept_name']}")

​
Next Steps

Congratulations! You’ve successfully made your first API calls to OMOPHub. Here’s what you can explore next:

Authentication

Learn about OAuth setup and API key management

Advanced Search

Master complex search queries and filters

Concept Mapping

Map concepts between different vocabularies

Use Cases

See real-world healthcare implementations

​
Common Issues

If you receive a 401 Unauthorized error:
  • Check that your API key is correct
  • Ensure you’re using the correct authorization header format
  • Verify your API key hasn’t expired
If you receive a 429 Too Many Requests error:
  • Check your current rate limit in the response headers
  • Implement exponential backoff for retries
  • Consider upgrading your plan for higher limits
If your search returns no results:
  • Try broader search terms
  • Check spelling and remove special characters
  • Use wildcards or partial matching
  • Verify the vocabulary ID is correct
⌘I