Skip to main content

​
Resolve a Single FHIR Coding

Translate a FHIR Coding (system URI + code) to an OMOP standard concept and CDM target table: 
result = client.fhir.resolve(
    system="http://snomed.info/sct",
    code="44054006",
    resource_type="Condition",
)
res = result["resolution"]
print(res["standard_concept"]["concept_name"])  # "Type 2 diabetes mellitus"
print(res["target_table"])                       # "condition_occurrence"
print(res["mapping_type"])                       # "direct"

​
Resolve a Non-Standard Code (Maps to Traversal)

ICD-10-CM and other classification codes are automatically mapped to their standard equivalents: 
result = client.fhir.resolve(
    system="http://hl7.org/fhir/sid/icd-10-cm",
    code="E11.9",
)
res = result["resolution"]
print(res["source_concept"]["vocabulary_id"])    # "ICD10CM"
print(res["standard_concept"]["vocabulary_id"])  # "SNOMED"
print(res["mapping_type"])                       # "mapped"
print(res["relationship_id"])                    # "Maps to"
print(res["target_table"])                       # "condition_occurrence"

​
Text-Only Resolution (Semantic Search Fallback)

When no structured code is available, pass the display text for BioLORD semantic search: 
result = client.fhir.resolve(
    display="Blood Sugar",
    resource_type="Observation",
)
res = result["resolution"]
print(res["standard_concept"]["concept_name"])  # "Glucose [Mass/volume] in Blood"
print(res["mapping_type"])                       # "semantic_match"
print(res["similarity_score"])                   # 0.91
print(res["target_table"])                       # "measurement"

​
Skip URI Resolution with vocabulary_id

If you already know the OMOP vocabulary, bypass the URI lookup: 
result = client.fhir.resolve(
    vocabulary_id="ICD10CM",
    code="E11.9",
)

​
Include Phoebe Recommendations

Get related concepts for phenotype development alongside the resolution: 
result = client.fhir.resolve(
    system="http://snomed.info/sct",
    code="44054006",
    include_recommendations=True,
    recommendations_limit=5,
)
for rec in result["resolution"]["recommendations"]:
    print(f"  {rec['concept_name']} ({rec['domain_id']}) via {rec['relationship_id']}")
    # "Hyperglycemia (Condition) via Has finding"
    # "Diabetic retinopathy (Condition) via Associated finding"

​
Include Mapping Quality Signal

Assess whether a resolution needs manual review: 
result = client.fhir.resolve(
    system="http://snomed.info/sct",
    code="44054006",
    include_quality=True,
)
print(result["resolution"]["mapping_quality"])  # "high", "medium", "low", or "manual_review"

​
Batch Resolution

Resolve up to 100 codings in a single call. Failed items are reported inline: 
result = client.fhir.resolve_batch([
    {"system": "http://snomed.info/sct", "code": "44054006"},
    {"system": "http://loinc.org", "code": "2339-0"},
    {"system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "197696"},
])

print(result["summary"])  # {"total": 3, "resolved": 3, "failed": 0}

for item in result["results"]:
    if "resolution" in item:
        res = item["resolution"]
        print(f"{res['source_concept']['concept_code']} -> {res['standard_concept']['concept_name']} -> {res['target_table']}")
    else:
        print(f"Failed: {item['error']['code']} - {item['error']['message']}")
Apply shared options to the entire batch: 
result = client.fhir.resolve_batch(
    [{"system": "http://snomed.info/sct", "code": "44054006"}],
    resource_type="Condition",
    include_quality=True,
)

​
CodeableConcept Resolution

Resolve a FHIR CodeableConcept with multiple codings. The resolver picks the best match per OHDSI vocabulary preference (SNOMED > RxNorm > LOINC > CVX > ICD-10): 
result = client.fhir.resolve_codeable_concept(
    coding=[
        {"system": "http://snomed.info/sct", "code": "44054006"},
        {"system": "http://hl7.org/fhir/sid/icd-10-cm", "code": "E11.9"},
    ],
    resource_type="Condition",
)

best = result["best_match"]["resolution"]
print(best["source_concept"]["vocabulary_id"])  # "SNOMED" (preferred)
print(best["target_table"])                     # "condition_occurrence"

# Other resolved codings ranked by preference
for alt in result["alternatives"]:
    print(f"  Alt: {alt['resolution']['source_concept']['vocabulary_id']}")

# Codings that failed to resolve
for fail in result["unresolved"]:
    print(f"  Failed: {fail['error']['code']}")
Falls back to the text field via semantic search when no coding resolves: 
result = client.fhir.resolve_codeable_concept(
    coding=[{"system": "http://loinc.org", "code": "99999-9"}],
    text="Blood Sugar",
    resource_type="Observation",
)
# best_match resolved via semantic search; failed coding in unresolved

​
Async Usage

All three methods are available on the async client: 
async with omophub.AsyncOMOPHub(api_key="oh_xxx") as client:
    result = await client.fhir.resolve(
        system="http://snomed.info/sct",
        code="44054006",
    )
    batch = await client.fhir.resolve_batch([
        {"system": "http://loinc.org", "code": "2339-0"},
    ])
    cc = await client.fhir.resolve_codeable_concept(
        coding=[{"system": "http://snomed.info/sct", "code": "44054006"}],
    )

​
Error Handling

The resolver raises standard SDK errors for API failures: 
from omophub import APIError

try:
    result = client.fhir.resolve(
        system="http://www.ama-assn.org/go/cpt",
        code="99213",
    )
except APIError as e:
    print(e.status_code)  # 403
    print(e.message)       # "vocabulary_restricted"
Error CodeHTTPCause
unknown_system400FHIR code system URI not recognized (includes a typo suggestion when close)
missing_input400Neither (system + code) / (vocabulary_id + code) / display provided
vocabulary_restricted403CPT4 excluded due to AMA licensing
concept_not_found404No concept found via lookup or semantic search
See the FHIR Resolver API Reference for full response schemas and field descriptions.