The official Python SDK for OMOPHub - a medical vocabulary API providing access to OHDSI ATHENA standardized vocabularies including SNOMED CT, ICD-10, RxNorm, LOINC, and 90+ other medical terminologies.
pip install omophubimport omophub
# Initialize the client
client = omophub.OMOPHub(api_key="oh_xxxxxxxxx")
# Get a concept by ID
concept = client.concepts.get(201826)
print(concept["concept_name"]) # "Type 2 diabetes mellitus"
# Search for concepts
results = client.search.basic("diabetes", vocabulary_ids=["SNOMED", "ICD10CM"])
for concept in results["concepts"]:
print(f"{concept['concept_id']}: {concept['concept_name']}")
# Get concept ancestors
ancestors = client.hierarchy.ancestors(201826, max_levels=3)
# Map concepts between vocabularies
mappings = client.mappings.get(201826, target_vocabularies=["ICD10CM"])import omophub
import asyncio
async def main():
async with omophub.AsyncOMOPHub(api_key="oh_xxx") as client:
concept = await client.concepts.get(201826)
print(concept["concept_name"])
asyncio.run(main())Set your API key in one of three ways:
# 1. Pass directly to client
client = omophub.OMOPHub(api_key="oh_xxxxxxxxx")
# 2. Set environment variable
# export OMOPHUB_API_KEY=oh_xxxxxxxxx
client = omophub.OMOPHub()
# 3. Set module-level variable
import omophub
omophub.api_key = "oh_xxxxxxxxx"
client = omophub.OMOPHub()Get your API key from the OMOPHub Dashboard.
client = omophub.OMOPHub(
api_key="oh_xxx",
base_url="https://api.omophub.com/v1", # API base URL
timeout=30.0, # Request timeout in seconds
max_retries=3, # Retry attempts for failed requests
vocab_version="2025.2", # Specific vocabulary version
)# Get concept by ID
concept = client.concepts.get(201826)
# Get concept by vocabulary code
concept = client.concepts.get_by_code("SNOMED", "73211009")
# Batch get concepts
result = client.concepts.batch([201826, 4329847, 73211009])
# Get autocomplete suggestions
suggestions = client.concepts.suggest("diab", vocabulary="SNOMED", limit=10)
# Get related concepts
related = client.concepts.related(201826, relatedness_types=["hierarchical", "semantic"])
# Get concept relationships
relationships = client.concepts.relationships(201826)# Basic search
results = client.search.basic(
"heart attack",
vocabulary_ids=["SNOMED"],
domain_ids=["Condition"],
page=1,
page_size=20,
)
# Advanced search with facets
results = client.search.advanced(
"myocardial infarction",
vocabularies=["SNOMED", "ICD10CM"],
standard_concepts_only=True,
)
# Semantic search
results = client.search.semantic("chest pain with shortness of breath")
# Fuzzy search (typo-tolerant)
results = client.search.fuzzy("diabetis") # finds "diabetes"
# Auto-pagination iterator
for concept in client.search.basic_iter("diabetes", page_size=100):
print(concept["concept_name"])# Get ancestors
ancestors = client.hierarchy.ancestors(
201826,
max_levels=5,
relationship_types=["Is a"],
)
# Get descendants
descendants = client.hierarchy.descendants(
201826,
max_levels=3,
standard_only=True,
)# Get mappings for a concept
mappings = client.mappings.get(
201826,
target_vocabularies=["ICD10CM", "Read"],
include_mapping_quality=True,
)
# Map concepts to target vocabulary
result = client.mappings.map(
source_concepts=[201826, 4329847],
target_vocabulary="ICD10CM",
)# List all vocabularies
vocabularies = client.vocabularies.list(include_stats=True)
# Get vocabulary details
snomed = client.vocabularies.get("SNOMED", include_domains=True)
# Get vocabulary statistics
stats = client.vocabularies.stats("SNOMED")# List all domains
domains = client.domains.list(include_statistics=True)
# Get domain details
condition = client.domains.get("Condition")
# Get concepts in a domain
concepts = client.domains.concepts("Drug", standard_only=True)import omophub
try:
client = omophub.OMOPHub(api_key="oh_xxx")
concept = client.concepts.get(999999999)
except omophub.NotFoundError as e:
print(f"Concept not found: {e.message}")
except omophub.AuthenticationError as e:
print(f"Authentication failed: {e.message}")
except omophub.RateLimitError as e:
print(f"Rate limited. Retry after {e.retry_after} seconds")
except omophub.ValidationError as e:
print(f"Invalid request: {e.message}")
except omophub.APIError as e:
print(f"API error {e.status_code}: {e.message}")
except omophub.OMOPHubError as e:
print(f"SDK error: {e.message}")The SDK is fully typed with TypedDict definitions for all API responses:
from omophub import OMOPHub, Concept
client = OMOPHub(api_key="oh_xxx")
concept: Concept = client.concepts.get(201826)
# IDE autocomplete works for all fields
print(concept["concept_id"])
print(concept["concept_name"])
print(concept["vocabulary_id"])MIT License - see LICENSE for details.