Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.omophub.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Translates codes between vocabularies using OMOP Maps to relationships. Supports both forward (source code to OMOP standard) and reverse (OMOP concept to source code) translation. Key R4/R5 difference: R4 responses use equivalence, R5/R6 use relationship.

​
Forward Translation

Translate a source code to its OMOP standard equivalent: 
curl "https://fhir.omophub.com/fhir/r4/ConceptMap/\$translate?\
sourceCode=E11.9&\
system=http://hl7.org/fhir/sid/icd-10-cm&\
targetSystem=https://fhir-terminology.ohdsi.org" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
POST with sourceCoding

curl -X POST "https://fhir.omophub.com/fhir/r4/ConceptMap/\$translate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Parameters",
    "parameter": [
      {
        "name": "sourceCoding",
        "valueCoding": {
          "system": "http://hl7.org/fhir/sid/icd-10-cm",
          "code": "E11.9"
        }
      },
      { "name": "targetSystem", "valueUri": "https://fhir-terminology.ohdsi.org" }
    ]
  }'

​
Reverse Translation

Look up the source code for an OMOP concept: 
curl "https://fhir.omophub.com/fhir/r4/ConceptMap/\$translate?\
targetCode=201826&\
system=https://fhir-terminology.ohdsi.org" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Parameters

​
Forward

ParameterTypeRequiredDescription
sourceCodecodeYes*Source code to translate
sourceCodingCodingYes*Alternative: Coding with system + code
systemuriYes*Source code system URI (required with sourceCode, included in sourceCoding)
targetSystemuriNoTarget code system (defaults to OMOP unified)
urluriNoCanonical URL of a specific FHIR-to-OMOP IG ConceptMap to translate through (e.g. http://hl7.org/fhir/uv/omop/ConceptMap/ConditionConcepts). When the code is present in that map, its target is returned; otherwise translation falls back to the default system-based resolution.
*Provide either sourceCode + system or sourceCoding.

​
Reverse

ParameterTypeRequiredDescription
targetCodecodeYes*OMOP concept_id to reverse-lookup
targetCodingCodingYes*Alternative: Coding with system + code
systemuriNoThe code system of the target concept (use https://fhir-terminology.ohdsi.org for OMOP unified, or a vocabulary-specific URI to filter)
*Provide either targetCode or targetCoding.

​
Response (R4)

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "result", "valueBoolean": true },
    {
      "name": "match",
      "part": [
        { "name": "equivalence", "valueCode": "equivalent" },
        {
          "name": "concept",
          "valueCoding": {
            "system": "https://fhir-terminology.ohdsi.org",
            "code": "201826",
            "display": "Type 2 diabetes mellitus"
          }
        },
        {
          "name": "product",
          "part": [
            {
              "name": "property",
              "valueUri": "http://omophub.com/fhir/property/domain-id"
            },
            { "name": "value", "valueString": "Condition" }
          ]
        },
        {
          "name": "product",
          "part": [
            {
              "name": "property",
              "valueUri": "http://omophub.com/fhir/property/target-table"
            },
            { "name": "value", "valueString": "condition_occurrence" }
          ]
        }
      ]
    }
  ]
}
The target-table product property is OMOPHub-exclusive. It tells ETL developers exactly which OMOP CDM table the translated concept belongs to.
$translate returns both Maps to and Maps to value targets. The latter decomposes composite concepts into a value concept (HL7 FHIR-to-OMOP IG Value-as-Concept pattern) — e.g. SNOMED “Allergy to penicillin” yields an “Allergy to drug” match (Maps to) and a “Penicillin G” match (Maps to value). Each match carries an OMOPHub-exclusive omop-relationship product (Maps to vs Maps to value) so you can route the value concept to value_as_concept_id. Administrative code systems (gender, encounter class, …) translate via the IG’s administrative ConceptMaps.

​
R5/R6 Difference

On the /fhir/r5/ and /fhir/r6/ endpoints, equivalence is renamed to relationship: 
{ "name": "relationship", "valueCode": "equivalent" }

​
Equivalence Mapping

OMOP RelationshipFHIR Equivalence
Maps toequivalent
Maps to valueequivalent
Is awider
Mapped fromnarrower
(no mapping)unmatched