We're excited to announce SDK v1.3.0 for both Python and R, bringing powerful new features and important API improvements for consistency and simplicity.

New Features

Complete Hierarchy in One Call

The new hierarchy.get() method retrieves both ancestors and descendants in a single request:

# Python
hierarchy = client.hierarchy.get(201826)  # Type 2 diabetes
print(f"Ancestors: {len(hierarchy['ancestors'])}")
print(f"Descendants: {len(hierarchy['descendants'])}")

# R
hierarchy <- client$hierarchy$get(201826)
cat("Ancestors:", length(hierarchy$ancestors), "\n")
cat("Descendants:", length(hierarchy$descendants), "\n")

Vocabulary Version Pinning

Pin your queries to specific vocabulary releases for reproducible research:

# Python - query specific vocabulary version
concept = client.concepts.get(201826, vocab_release="2025.1")
mappings = client.mappings.get(201826, vocab_release="2025.1")

# R - same pattern
concept <- client$concepts$get(201826, vocab_release = "2025.1")
mappings <- client$mappings$get(201826, vocab_release = "2025.1")

New Vocabulary Methods

vocabularies.domain_stats(vocabulary_id, domain_id) - Get statistics for a specific domain within a vocabulary
vocabularies.concept_classes() - List all available concept classes

Include Hierarchy with Concepts

Fetch concept details with hierarchy in one request:

# Python
concept = client.concepts.get(201826, include_hierarchy=True)

Breaking Changes

This release includes parameter renames for API consistency. Update your code according to this migration table:

Old Parameter	New Parameter	Affected Methods
`limit`	`page_size`	All paginated methods
`vocabulary`	`vocabulary_ids`	`suggest()`, search methods
`domain`	`domain_ids`	`suggest()`, search methods
`target_vocabularies`	`target_vocabulary`	`mappings.get()`
`relationship_type`	`relationship_ids`	`relationships.get()`
`vocabulary_id`	`vocabulary_ids`	`hierarchy.ancestors()`, `hierarchy.descendants()`
`include_deprecated`	`include_invalid`	Hierarchy methods

Before and After

# Before (v1.2.x)
results = client.concepts.suggest("diabetes", vocabulary="SNOMED", limit=10)
mappings = client.mappings.get(201826, target_vocabularies=["ICD10CM"])

# After (v1.3.0)
results = client.concepts.suggest("diabetes", vocabulary_ids="SNOMED", page_size=10)
mappings = client.mappings.get(201826, target_vocabulary=["ICD10CM"])

API Simplifications

Several methods have been streamlined with fewer parameters:

mappings.get() - Simplified to target_vocabulary, include_invalid, vocab_release
domains.list() - Now takes single include_stats parameter
vocabularies.get() - Now takes only vocabulary_id
vocabularies.domains() - Removed pagination, returns all domains

Default Changes

Method	Parameter	Old Default	New Default
`concepts.batch()`	`standard_only`	`False`	`True`
`vocabularies.list()`	`page_size`	100	20
`relationships.get()`	`page_size`	50	100

Batch Limit Reduced

The maximum concepts per batch request has been reduced from 1000 to 100 for improved reliability.

Upgrade Guide

Update SDK: pip install --upgrade omophub or install.packages("omophub")
Find and replace deprecated parameters using the migration table above
Review batch operations if you're batching more than 100 concepts
Test thoroughly - the standard_only=True default may change your results

Resources

Shipping more new features for you soon!