> ## 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.

# FHIR ConceptMap/$translate across OMOP vocabularies

> Translate codes between vocabularies with FHIR $translate - SNOMED to ICD-10, ICD-9 to SNOMED, RxNorm to ATC, and other OMOP standard mappings.

## 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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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

| Parameter      | Type   | Required | Description                                                                     |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `sourceCode`   | code   | Yes\*    | Source code to translate                                                        |
| `sourceCoding` | Coding | Yes\*    | Alternative: Coding with system + code                                          |
| `system`       | uri    | Yes\*    | Source code system URI (required with `sourceCode`, included in `sourceCoding`) |
| `targetSystem` | uri    | No       | Target code system (defaults to OMOP unified)                                   |

\*Provide either `sourceCode` + `system` or `sourceCoding`.

### Reverse

| Parameter      | Type   | Required | Description                                                                                                                               |
| -------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `targetCode`   | code   | Yes\*    | OMOP concept\_id to reverse-lookup                                                                                                        |
| `targetCoding` | Coding | Yes\*    | Alternative: Coding with system + code                                                                                                    |
| `system`       | uri    | No       | The 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)

```json theme={null}
{
  "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" }
          ]
        }
      ]
    }
  ]
}
```

<Note>
  The `target-table` product property is OMOPHub-exclusive. It tells ETL developers exactly which OMOP CDM table the translated concept belongs to.
</Note>

## R5/R6 Difference

On the `/fhir/r5/` and `/fhir/r6/` endpoints, `equivalence` is renamed to `relationship`:

```json theme={null}
{ "name": "relationship", "valueCode": "equivalent" }
```

## Equivalence Mapping

| OMOP Relationship | FHIR Equivalence |
| ----------------- | ---------------- |
| Maps to           | `equivalent`     |
| Maps to value     | `equivalent`     |
| Is a              | `wider`          |
| Mapped from       | `narrower`       |
| (no mapping)      | `unmatched`      |