---
name: Omop Hub
description: Use when working with medical vocabularies, standardized clinical concepts, concept mapping, ETL pipelines, clinical data integration, or building healthcare applications that need to translate between different medical coding systems (SNOMED, ICD10, RxNorm, etc.)
metadata:
    mintlify-proj: omophub
    version: "1.0"
---

# OMOPHub Skill

## Product Summary

OMOPHub is an API-first platform for accessing and working with OMOP (Observational Medical Outcomes Partnership) standardized medical vocabularies and concepts. It provides REST APIs and SDKs (Python, R) to search, map, and traverse medical concepts across multiple vocabularies including SNOMED, ICD10CM, ICD10PCS, RxNorm, and others. The platform enables healthcare organizations to standardize clinical data, build ETL pipelines, and integrate medical terminology into applications. Access the API at `https://api.omophub.com/v1/` with Bearer token authentication. SDKs are available for Python and R with client initialization using API keys.

## When to Use

Reach for OMOPHub when:
- Building ETL pipelines to map clinical data from source systems to OMOP standard concepts
- Searching for medical concepts across multiple vocabularies (conditions, drugs, procedures, measurements)
- Creating concept mappings between different coding systems (e.g., ICD10 to SNOMED)
- Validating or enriching clinical data with standardized concept IDs
- Analyzing concept relationships and hierarchies (parent/child, related concepts)
- Integrating medical terminology into healthcare applications or research platforms
- Performing bulk concept operations on large datasets
- Developing clinical decision support or phenotyping logic that requires standardized concepts

## Quick Reference

### Core API Endpoints

| Task | Endpoint | Method |
|------|----------|--------|
| Search concepts by text | `/search/basic-search` | POST |
| Semantic similarity search | `/search/semantic-search` | POST |
| Get concept by ID | `/concepts/{concept_id}` | GET |
| Get concept by code | `/concepts/code/{code}` | GET |
| Map concepts | `/mappings/map-concepts` | POST |
| Get concept mappings | `/mappings/get-concept-mappings` | GET |
| Get concept ancestors | `/hierarchy/get-concept-ancestors` | GET |
| Get concept descendants | `/hierarchy/get-concept-descendants` | GET |
| List vocabularies | `/vocabularies/list-vocabularies` | GET |
| Get domain concepts | `/domains/get-domain-concepts` | GET |

### Authentication

All requests require Bearer token in Authorization header:
```
Authorization: Bearer YOUR_API_KEY
```

### Python SDK Initialization

```python
from omophub import OMOPHubClient

client = OMOPHubClient(api_key="YOUR_API_KEY")
```

### Common Filters

| Parameter | Values | Purpose |
|-----------|--------|---------|
| `vocabulary_ids` | SNOMED, ICD10CM, ICD10PCS, RxNorm, LOINC, CPT4, etc. | Filter by source vocabulary |
| `domain_ids` | Condition, Drug, Procedure, Measurement, Observation | Filter by clinical domain |
| `standard_concept` | S (standard), C (classification), N (non-standard) | Filter concept type |
| `page_size` | 1-1000 (default 50) | Results per page |
| `algorithm` | semantic, lexical, hybrid (default) | Search algorithm type |

## Decision Guidance

### When to Use Search Algorithms

| Scenario | Algorithm | Reason |
|----------|-----------|--------|
| Exact medical term match | `lexical` | Fast, precise for known terms |
| Conceptual similarity ("heart attack" → "MI") | `semantic` | Neural embeddings understand meaning |
| Typo tolerance and fuzzy matching | `hybrid` or `lexical` | Character-level similarity |
| Unknown or varied terminology | `semantic` | Handles synonyms and related concepts |
| Performance-critical bulk operations | `lexical` | Faster than semantic (50-200ms vs 15-50ms) |

### When to Use Batch vs Single Operations

| Situation | Approach | Benefit |
|-----------|----------|---------|
| Mapping 1-10 concepts | Single `/map-concepts` | Simpler, immediate response |
| Mapping 100+ concepts | `/batch-map-concepts` | Efficient, handles large datasets |
| Exploring relationships | Single concept queries | Interactive, exploratory |
| Validating entire dataset | Batch hierarchy queries | Bulk validation in one call |

### Standard Concept vs All Concepts

| Use Case | Filter | Reason |
|----------|--------|--------|
| Clinical research, OMOP databases | `standard_only=true` | Ensures data quality, standardization |
| Historical data analysis | `include_invalid=true` | Captures deprecated concepts |
| Mapping source data | No filter initially | Find all possible matches, then validate |

## Workflow

### 1. Search for Concepts
Start by searching for the clinical term you need to standardize:
```python
results = client.search.basic_search(
    query="type 2 diabetes",
    vocabulary_ids=["SNOMED", "ICD10CM"],
    domain_ids=["Condition"],
    standard_concept="S"
)
```

### 2. Examine Concept Details
Retrieve full concept information including relationships and metadata:
```python
concept = client.concepts.get_concept(concept_id=44054006)
# Returns: concept_name, concept_code, vocabulary_id, domain_id, relationships
```

### 3. Map Between Vocabularies
Find equivalent concepts across different coding systems:
```python
mappings = client.mappings.map_concepts(
    source_concept_ids=[44054006],
    target_vocabularies=["ICD10CM"]
)
```

### 4. Validate Mappings
Check mapping quality and coverage before using in production:
```python
quality = client.mappings.get_mapping_quality(
    source_vocab="SNOMED",
    target_vocab="ICD10CM"
)
```

### 5. Explore Hierarchies
Understand concept relationships for phenotyping or gap analysis:
```python
ancestors = client.hierarchy.get_concept_ancestors(concept_id=44054006)
descendants = client.hierarchy.get_concept_descendants(concept_id=44054006)
```

### 6. Batch Process Large Datasets
For ETL pipelines, use batch operations:
```python
batch_results = client.mappings.batch_map_concepts(
    concept_ids=[44054006, 201826, 443729],
    target_vocabularies=["ICD10CM"]
)
```

## Common Gotchas

- **Similarity threshold out of range**: Ensure threshold is between 0.0 and 1.0. Values like 1.5 will fail with `INVALID_THRESHOLD`.
- **Semantic search pagination**: When using `algorithm: "semantic"`, `total_candidates` and pagination counts are approximate. Always check `has_next` in response to determine if more results exist.
- **Standard concept flag confusion**: "S" = standard (preferred), "C" = classification (grouping), "N" = non-standard (deprecated). Most analyses should use `standard_concept: "S"`.
- **Missing mappings**: Not all concepts have mappings to all vocabularies. Check `get_mapping_coverage()` before assuming a mapping exists.
- **Vocabulary version mismatch**: API responses include `vocab_release` in metadata. Ensure your application handles vocabulary version changes.
- **Rate limiting**: Respect rate limits on bulk operations. Use batch endpoints for large datasets rather than looping single requests.
- **Deprecated concepts**: By default, `include_invalid=true` returns deprecated concepts. Explicitly set `include_invalid=false` if you only want active concepts.
- **Domain filtering**: Some concepts exist in multiple domains. Always filter by `domain_ids` to get relevant results (e.g., "Condition" vs "Observation").

## Verification Checklist

Before submitting work with OMOPHub:

- [ ] Verified API key is valid and has appropriate permissions
- [ ] Confirmed correct vocabulary IDs are being used (SNOMED vs ICD10CM vs RxNorm)
- [ ] Checked that `standard_concept` filter matches your use case (S for standard, C for classification)
- [ ] Validated similarity threshold is between 0.0 and 1.0 for semantic searches
- [ ] Tested batch operations with small dataset first before scaling to production
- [ ] Confirmed mapping coverage exists for source-to-target vocabulary pair
- [ ] Checked `vocab_release` in response metadata matches expected version
- [ ] Handled pagination correctly (using `has_next` for semantic searches)
- [ ] Tested error responses and implemented retry logic for rate-limited requests
- [ ] Verified concept IDs in results match expected domains and vocabularies

## Resources

- **Comprehensive API navigation**: https://docs.omophub.com/llms.txt
- **API Reference**: https://docs.omophub.com/api-reference/introduction
- **Python SDK Documentation**: https://docs.omophub.com/sdks/python/overview
- **Search Endpoints Guide**: https://docs.omophub.com/api-reference/search/basic-search

---

> For additional documentation and navigation, see: https://docs.omophub.com/llms.txt