We're excited to announce the first official release of the OMOPHub Python SDK, making it easier than ever to integrate OHDSI vocabularies into your Python applications.

Installation

Install via pip:

pip install omophub

Quick Start

import omophub

# Initialize the client
client = omophub.OMOPHub(api_key="oh_xxxxxxxxx")

# Search for concepts
results = client.search.basic("diabetes")
for concept in results.concepts:
    print(f"{concept.concept_id}: {concept.concept_name}")

# Get concept details
concept = client.concepts.get(201826)
print(concept.concept_name)  # "Type 2 diabetes mellitus"

Key Features

Type-Safe Client

The SDK provides full type hints and IDE autocompletion for all API responses:

concept = client.concepts.get(201826)
concept.concept_id      # int
concept.concept_name    # str
concept.vocabulary_id   # str

Automatic Pagination

Easily iterate through large result sets:

# Fetch all results automatically
all_concepts = client.search.basic_all("aspirin", page_size=100)

# Or use manual pagination
page = client.search.basic("aspirin", page=1, page_size=50)
while page.meta.pagination.has_next:
    page = client.search.basic("aspirin", page=page.meta.pagination.page + 1)

Comprehensive Error Handling

Structured exceptions for all error scenarios:

from omophub.exceptions import NotFoundError, RateLimitError

try:
    concept = client.concepts.get(999999999)
except NotFoundError:
    print("Concept not found")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")

Vocabulary Versioning

Pin to specific vocabulary versions for reproducible research:

import omophub

client = omophub.OMOPHub(
    api_key="your-api-key",
    vocab_version="2025.2"
)

Resources

We welcome contributions and feedback on GitHub!