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: Install the SDK

Choose your preferred programming language and install the OMOPHub SDK: 
# Python - Install the OMOPHub SDK
pip install omophub

​
Step 2: Set Up Authentication

Initialize the SDK client with your API key: 
# Python
from omophub import OMOPHub

# Option 1: Use environment variable (recommended)
# export OMOPHUB_API_KEY="oh_xxxxxxxxx"
client = OMOPHub()

# Option 2: Pass API key directly
client = OMOPHub(api_key="oh_xxxxxxxxx")
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
results = client.search.basic("hypertension", page_size=5)

# Display the results
for concept in results.data:
    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
concept = client.concepts.get(concept_id)

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
relationships = client.concepts.relationships(concept_id)
print(f"\nFound {len(relationships.data)} relationships")

​
Step 5: Navigate Concept Hierarchies

Explore parent and child concepts: 
# Python - Get parent concepts (ancestors)
ancestors = client.hierarchy.ancestors(320128, max_levels=2)

print("Parent concepts:")
for ancestor in ancestors.concepts:
    indent = "  " * ancestor.min_levels_of_separation
    print(f"{indent}{ancestor.concept_name}")

# Get child concepts (descendants)
descendants = client.hierarchy.descendants(320128, max_levels=2)

print("\nChild concepts:")
for descendant in descendants.concepts:
    indent = "  " * descendant.min_levels_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