Quickstart - search, map, and resolve codes in 5 min

Get up and running with the OMOPHub API in 5 minutes.

Prerequisites

You’ll need:

An OMOPHub account (sign up here)
An API key (generate one here)
Python 3.10+, R 4.1+, or cURL

Step 1: Install the SDK

pip install omophub

install.packages("omophub")

# No installation needed - just your API key

Step 2: Set Up Authentication

import omophub

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

# Option 2: pass directly
client = omophub.OMOPHub(api_key="oh_xxxxxxxxx")

library(omophub)

# Option 1: environment variable (recommended)
# Sys.setenv(OMOPHUB_API_KEY = "oh_xxxxxxxxx")
client <- OMOPHubClient$new()

# Option 2: pass directly
client <- OMOPHubClient$new(api_key = "oh_xxxxxxxxx")

# Include in every request header
curl -H "Authorization: Bearer oh_xxxxxxxxx" \
  "https://api.omophub.com/v1/vocabularies"

Never hardcode your API key in source code. Use environment variables or a secrets manager in production.

Step 3: Search for Concepts

Search across 11M+ concepts by keyword, then by meaning:

# Keyword search
results = client.search.basic("hypertension", page_size=5)
for concept in results["concepts"]:
    print(f"{concept['concept_id']}: {concept['concept_name']} ({concept['vocabulary_id']})")

# Semantic search - find concepts by clinical meaning, not just keyword match
results = client.search.semantic("high blood pressure that comes and goes", page_size=5)
for concept in results["concepts"]:
    print(f"{concept['concept_id']}: {concept['concept_name']}")

# Keyword search
results <- client$search$basic("hypertension", page_size = 5)
for (concept in results$concepts) {
  cat(sprintf("%s: %s (%s)\n",
    concept$concept_id, concept$concept_name, concept$vocabulary_id))
}

# Semantic search - find concepts by clinical meaning
results <- client$search$semantic(
  "high blood pressure that comes and goes",
  page_size = 5
)

# Keyword search
curl "https://api.omophub.com/v1/search/concepts?query=hypertension&page_size=5" \
  -H "Authorization: Bearer oh_xxxxxxxxx"

# Semantic search
curl "https://api.omophub.com/v1/search/semantic?query=high+blood+pressure+that+comes+and+goes&page_size=5" \
  -H "Authorization: Bearer oh_xxxxxxxxx"

Semantic search uses neural embeddings to match by clinical meaning. Try it when keyword search doesn’t find what you need - it handles synonyms, abbreviations, and natural-language descriptions.

Step 4: Get Concept Details

Look up a specific concept by its OMOP concept_id:

concept = client.concepts.get(201826)
print(f"Name:       {concept['concept_name']}")        # Type 2 diabetes mellitus
print(f"Code:       {concept['concept_code']}")         # 44054006
print(f"Vocabulary: {concept['vocabulary_id']}")        # SNOMED
print(f"Domain:     {concept['domain_id']}")            # Condition
print(f"Standard:   {concept['standard_concept']}")     # S

concept <- client$concepts$get(201826)
cat(sprintf("Name: %s\n",       concept$concept_name))
cat(sprintf("Code: %s\n",       concept$concept_code))
cat(sprintf("Vocabulary: %s\n", concept$vocabulary_id))
cat(sprintf("Domain: %s\n",     concept$domain_id))

curl "https://api.omophub.com/v1/concepts/201826" \
  -H "Authorization: Bearer oh_xxxxxxxxx"

Step 5: Navigate Hierarchies

Walk the ancestor / descendant tree to expand a concept set:

# Ancestors (parents)
result = client.hierarchy.ancestors(201826, max_levels=2)
for ancestor in result["ancestors"]:
    level = ancestor.get("hierarchy_level", 0)
    print(f"{'  ' * level}{ancestor['concept_name']}")

# Descendants (children)
result = client.hierarchy.descendants(201826, max_levels=1)
print(f"\n{len(result['descendants'])} child concepts")

# Ancestors
result <- client$hierarchy$ancestors(201826, max_levels = 2)
for (ancestor in result$ancestors) {
  level <- if (is.null(ancestor$hierarchy_level)) 0 else ancestor$hierarchy_level
  cat(strrep("  ", level), ancestor$concept_name, "\n", sep = "")
}

# Descendants
result <- client$hierarchy$descendants(201826, max_levels = 1)
cat(sprintf("%d child concepts\n", length(result$descendants)))

# Ancestors
curl "https://api.omophub.com/v1/concepts/201826/ancestors?max_levels=2" \
  -H "Authorization: Bearer oh_xxxxxxxxx"

# Descendants
curl "https://api.omophub.com/v1/concepts/201826/descendants?max_levels=1" \
  -H "Authorization: Bearer oh_xxxxxxxxx"

Step 6: Map Between Vocabularies

Translate codes across SNOMED, ICD-10, LOINC, RxNorm, and every other OMOP vocabulary:

# Map SNOMED "Type 2 diabetes" to ICD-10-CM
result = client.mappings.get(201826, target_vocabulary="ICD10CM")
for m in result["data"]["mappings"]:
    print(f"{m['relationship_id']}: {m['target_concept_name']} "
          f"({m['target_vocabulary_id']}: {m['target_concept_code']})")

result <- client$mappings$get(201826, target_vocabulary = "ICD10CM")
for (m in result$data$mappings) {
  cat(sprintf("%s: %s (%s: %s)\n",
    m$relationship_id,
    m$target_concept_name,
    m$target_vocabulary_id,
    m$target_concept_code
  ))
}

curl "https://api.omophub.com/v1/concepts/201826/mappings?target_vocabularies=ICD10CM" \
  -H "Authorization: Bearer oh_xxxxxxxxx"

For ETL workloads, the batch endpoint client.mappings.map(target_vocabulary="...", source_concepts=[...]) maps up to 100 concepts per request and counts as a single API call against your quota.

Step 7: Resolve a FHIR Code to OMOP

This is the single call no other terminology server offers - send a FHIR Coding (system URI + code), get back the OMOP standard concept, domain, mapping type, and the exact CDM target table for ETL placement:

result = client.fhir.resolve(
    system="http://snomed.info/sct",
    code="44054006",
    resource_type="Condition",
)
res = result["resolution"]
print(f"Standard concept: {res['standard_concept']['concept_id']} - {res['standard_concept']['concept_name']}")
print(f"Domain:           {res['standard_concept']['domain_id']}")
print(f"Target table:     {res['target_table']}")         # condition_occurrence
print(f"Mapping type:     {res['mapping_type']}")         # direct

result <- client$fhir$resolve(
  system = "http://snomed.info/sct",
  code = "44054006",
  resource_type = "Condition"
)
res <- result$resolution
cat(sprintf("Standard concept: %d - %s\n",
  res$standard_concept$concept_id,
  res$standard_concept$concept_name))
cat(sprintf("Target table: %s\n", res$target_table))
cat(sprintf("Mapping type: %s\n", res$mapping_type))

curl -X POST "https://api.omophub.com/v1/fhir/resolve" \
  -H "Authorization: Bearer oh_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "system": "http://snomed.info/sct",
    "code": "44054006",
    "resource_type": "Condition"
  }'

The Resolver handles URI → OMOP vocabulary lookup, Maps to traversal for non-standard codes, and semantic fallback for display-text-only inputs in a single call. For the full response shape, batch variants, and the CodeableConcept endpoint, see the FHIR Integration guide.

Next Steps

FHIR Integration

The complete FHIR story - Resolver for ETL, Terminology Service for clients, and when to use which.

FHIR Terminology Service

$lookup, $translate, $validate-code, $expand, $subsumes reference.

AI & MCP Server

Connect Claude, Cursor, or VS Code to medical vocabularies via the MCP Server.

Python SDK

Full SDK reference: search, concepts, hierarchy, mappings, FHIR resolver.

Node.js / TypeScript SDK

Typed client with discriminated { data, error } returns and async iterators.

R SDK

R6 client for vocabulary access in R workflows.

API Reference

Complete endpoint documentation with request / response schemas.

Workflows

Real-world workflows: clinical coding, phenotype development, lab normalization, and more.

Common Issues

401 Unauthorized

Check that your API key is correct and starts with oh_
Ensure the Authorization: Bearer <key> header format is exact
Verify the key at dashboard.omophub.com/api-keys

429 Rate Limited

Free tier: 2 requests per second, monthly call quota per plan
Use batch endpoints (concepts, mappings, semantic search) to reduce call count - each batch counts as one API call
Respect the Retry-After response header
See Rate Limits for plan-specific limits

No Results Found

Try broader search terms or remove filters
Use semantic search for natural-language queries (Step 3)
Check vocabulary_id spelling - it’s SNOMED, not SNOMED-CT; ICD10CM, not ICD-10-CM
Confirm the target vocabulary is currently supported via client.vocabularies.list()

Getting Started

Integrations

Workflows

Production

Quickstart - search, map, and resolve codes in 5 min

Prerequisites

Step 1: Install the SDK

Step 2: Set Up Authentication

Step 3: Search for Concepts

Step 4: Get Concept Details

Step 5: Navigate Hierarchies

Step 6: Map Between Vocabularies

Step 7: Resolve a FHIR Code to OMOP

Next Steps

FHIR Integration

FHIR Terminology Service

AI & MCP Server

Python SDK

Node.js / TypeScript SDK

R SDK

API Reference

Workflows

Common Issues

​Prerequisites

​Step 1: Install the SDK

​Step 2: Set Up Authentication

​Step 3: Search for Concepts

​Step 4: Get Concept Details

​Step 5: Navigate Hierarchies

​Step 6: Map Between Vocabularies

​Step 7: Resolve a FHIR Code to OMOP

​Next Steps

FHIR Integration

FHIR Terminology Service

AI & MCP Server

Python SDK

Node.js / TypeScript SDK

R SDK

API Reference

Workflows

​Common Issues

Prerequisites

Step 1: Install the SDK

Step 2: Set Up Authentication

Step 3: Search for Concepts

Step 4: Get Concept Details

Step 5: Navigate Hierarchies

Step 6: Map Between Vocabularies

Step 7: Resolve a FHIR Code to OMOP

Next Steps

Common Issues