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

# Map Concepts

> Map medical concepts between OMOP vocabularies to find equivalent or related concepts across SNOMED, ICD-10, LOINC, RxNorm, and other terminologies.

## Overview

This endpoint maps medical concepts from source vocabularies to target vocabularies, finding equivalent or related concepts across different medical terminology systems. It's essential for healthcare data integration, cross-system interoperability, and clinical data standardization.

## Request Body

<ParamField name="source_concepts" type="array">
  Array of source OMOP concept IDs to map (1-100 concepts). Use this OR `source_codes`, not both.

  <br />

  **Important**: These must be OMOP concept IDs (internal database IDs), NOT vocabulary-specific codes. Use `/v1/concepts/by-code/{vocabulary}/{code}` to look up concept IDs from codes, or use `source_codes` parameter instead.

  <br />

  **Example**: `[201826, 192671]` (OMOP concept IDs for Type 2 diabetes and Myocardial infarction)
</ParamField>

<ParamField name="source_codes" type="array">
  Array of vocabulary/code pairs to map (1-100 concepts). Use this OR `source_concepts`, not both.

  <br />

  This allows mapping directly from source system codes (e.g., SNOMED codes) without first looking up the OMOP concept ID.

  <br />

  **Example**:

  ```json theme={null}
  [
    {"vocabulary_id": "SNOMED", "concept_code": "44054006"},
    {"vocabulary_id": "SNOMED", "concept_code": "22298006"}
  ]
  ```
</ParamField>

<ParamField name="target_vocabulary" type="string" required>
  Target vocabulary identifier to map concepts to

  <br />

  **Examples**: `"ICD10CM"`, `"SNOMED"`, `"ICD9CM"`, `"LOINC"`, `"RXNORM"`
</ParamField>

<ParamField name="mapping_type" type="string">
  Type of concept mapping to filter results by. When not specified, all mapping types are returned.

  <br />

  **Options**:

  * `"direct"` - Direct mappings only (Maps to, Mapped from)
  * `"equivalent"` - Equivalent concepts (Maps to, Source - contains, Has precise ingredient)
  * `"broader"` - Broader concepts (Is a, Subsumes, Has ingredient)
  * `"narrower"` - Narrower concepts (Subsumes, Consists of)
</ParamField>

<ParamField name="include_invalid" type="boolean" default="true">
  Include invalid/deprecated concepts in mapping results
</ParamField>

## Query Parameters

<ParamField query="vocab_release" type="string">
  Specific vocabulary release version to use for mapping (e.g., "2025.1", "2024.2").
  When not specified, uses the default/latest vocabulary version.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="error" type="object">
  Error information (present only on error responses)

  <Expandable title="error">
    <ResponseField name="code" type="string">
      Error code identifier (e.g., "INVALID\_VOCABULARY", "RATE\_LIMIT\_EXCEEDED")
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error message
    </ResponseField>

    <ResponseField name="details" type="object">
      Additional error details including supported vocabularies and validation failures

      <Expandable title="details">
        <ResponseField name="supported_vocabularies" type="array">
          List of supported vocabulary names when vocabulary validation fails
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="object">
  Contains the concept mapping results

  <Expandable title="data">
    <ResponseField name="mappings" type="array">
      Array of concept mappings found

      <Expandable title="mappings">
        <ResponseField name="source_concept_id" type="integer">
          OMOP concept ID of the source concept
        </ResponseField>

        <ResponseField name="source_concept_name" type="string">
          Name of the source concept
        </ResponseField>

        <ResponseField name="source_vocabulary_id" type="string">
          Vocabulary of the source concept
        </ResponseField>

        <ResponseField name="target_concept_id" type="integer">
          OMOP concept ID of the mapped target concept
        </ResponseField>

        <ResponseField name="target_concept_name" type="string">
          Name of the target concept
        </ResponseField>

        <ResponseField name="target_vocabulary_id" type="string">
          Vocabulary of the target concept
        </ResponseField>

        <ResponseField name="target_concept_code" type="string">
          Original source code in the target vocabulary
        </ResponseField>

        <ResponseField name="relationship_id" type="string">
          Type of relationship between concepts
        </ResponseField>

        <ResponseField name="relationship_name" type="string">
          Human-readable relationship description
        </ResponseField>

        <ResponseField name="mapping_confidence" type="number">
          Confidence score for the mapping (0.0 to 1.0)
        </ResponseField>

        <ResponseField name="valid_start_date" type="string">
          Start date when the mapping became valid
        </ResponseField>

        <ResponseField name="valid_end_date" type="string">
          End date when the mapping expires
        </ResponseField>

        <ResponseField name="source_concept_code" type="string">
          Original source code in the source vocabulary
        </ResponseField>

        <ResponseField name="invalid_reason" type="string">
          Reason if the mapping is invalid, null otherwise
        </ResponseField>

        <ResponseField name="mapping_type" type="string">
          Classification of the mapping: direct, equivalent, broader, narrower, or related
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Response metadata

  <Expandable title="meta">
    <ResponseField name="request_id" type="string">
      Unique request identifier for tracing and support
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp of when the request was processed
    </ResponseField>

    <ResponseField name="vocab_release" type="string">
      Vocabulary release version used for this request
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL (ICD-10 to SNOMED) theme={null}
  curl -X POST "https://api.omophub.com/v1/concepts/map" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "source_codes": [
        {"vocabulary_id": "ICD10CM", "concept_code": "E11.9"},
        {"vocabulary_id": "ICD10CM", "concept_code": "I21.9"}
      ],
      "target_vocabulary": "SNOMED",
      "mapping_type": "direct"
    }'
  ```

  ```bash cURL (with OMOP concept IDs) theme={null}
  curl -X POST "https://api.omophub.com/v1/concepts/map" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "source_concepts": [45576876, 45591524],
      "target_vocabulary": "SNOMED",
      "mapping_type": "direct",
      "include_invalid": false
    }'
  ```

  ```javascript JavaScript theme={null}
  // Map ICD-10 codes to SNOMED
  const response = await fetch('https://api.omophub.com/v1/concepts/map', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      source_codes: [
        { vocabulary_id: "ICD10CM", concept_code: "E11.9" },
        { vocabulary_id: "ICD10CM", concept_code: "I21.9" }
      ],
      target_vocabulary: "SNOMED",
      mapping_type: "direct"
    })
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.omophub.com/v1/concepts/map"

  # Map ICD-10 codes to SNOMED standard concepts
  payload = {
      "source_codes": [
          {"vocabulary_id": "ICD10CM", "concept_code": "E11.9"},
          {"vocabulary_id": "ICD10CM", "concept_code": "I21.9"}
      ],
      "target_vocabulary": "SNOMED",
      "mapping_type": "direct"
  }

  response = requests.post(
      url,
      json=payload,
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "mappings": [
        {
          "source_concept_id": 45576876,
          "source_concept_name": "Type 2 diabetes mellitus without complications",
          "source_concept_code": "E11.9",
          "source_vocabulary_id": "ICD10CM",
          "target_concept_id": 201826,
          "target_concept_name": "Type 2 diabetes mellitus",
          "target_concept_code": "44054006",
          "target_vocabulary_id": "SNOMED",
          "relationship_id": "Maps to",
          "relationship_name": "Maps to",
          "valid_start_date": "2023-01-01",
          "valid_end_date": "2099-12-31",
          "invalid_reason": null,
          "mapping_confidence": 1.0,
          "mapping_type": "direct"
        },
        {
          "source_concept_id": 45591524,
          "source_concept_name": "Acute myocardial infarction, unspecified",
          "source_concept_code": "I21.9",
          "source_vocabulary_id": "ICD10CM",
          "target_concept_id": 4329847,
          "target_concept_name": "Myocardial infarction",
          "target_concept_code": "22298006",
          "target_vocabulary_id": "SNOMED",
          "relationship_id": "Maps to",
          "relationship_name": "Maps to",
          "valid_start_date": "2023-01-01",
          "valid_end_date": "2099-12-31",
          "invalid_reason": null,
          "mapping_confidence": 1.0,
          "mapping_type": "direct"
        }
      ]
    },
    "meta": {
      "request_id": "req_abc123",
      "timestamp": "2025-01-05T12:00:00.000Z",
      "vocab_release": "2025.1"
    }
  }
  ```
</ResponseExample>

## Understanding OMOP Mapping Direction

<Warning>
  In OMOP, mappings go from **non-standard** concepts TO **standard** concepts. This means:

  * **ICD-10-CM → SNOMED** works (ICD-10 is non-standard, SNOMED is standard)
  * **SNOMED → ICD-10-CM** often returns empty (SNOMED concepts are already standard - they are mapping *targets*, not *sources*)

  If you get empty results, check whether your source concept is already a standard concept. Use `GET /v1/concepts/{id}` to check the `standard_concept` field - if it's `"S"`, try mapping in the opposite direction.
</Warning>

## Usage Examples

### ICD-10 to SNOMED (most common use case)

Map ICD-10-CM diagnosis codes to SNOMED standard concepts:

```json theme={null}
{
  "source_codes": [
    {"vocabulary_id": "ICD10CM", "concept_code": "E11.9"},
    {"vocabulary_id": "ICD10CM", "concept_code": "I21.9"}
  ],
  "target_vocabulary": "SNOMED",
  "mapping_type": "direct"
}
```

### Cross-System Integration

Map multiple ICD-10 codes for EHR standardization:

```json theme={null}
{
  "source_codes": [
    {"vocabulary_id": "ICD10CM", "concept_code": "E11.9"},
    {"vocabulary_id": "ICD10CM", "concept_code": "I21.9"},
    {"vocabulary_id": "ICD10CM", "concept_code": "J44.1"}
  ],
  "target_vocabulary": "SNOMED",
  "mapping_type": "direct",
  "include_invalid": false
}
```

### Drug Mapping

Map drug codes from NDC to RxNorm:

```json theme={null}
{
  "source_codes": [
    {"vocabulary_id": "NDC", "concept_code": "00002-4462-30"},
    {"vocabulary_id": "NDC", "concept_code": "00093-3147-01"}
  ],
  "target_vocabulary": "RxNorm",
  "mapping_type": "equivalent"
}
```

### Using OMOP Concept IDs

If you already have OMOP concept IDs (e.g., from a search result), use `source_concepts` instead of `source_codes`:

```json theme={null}
{
  "source_concepts": [45576876, 45591524],
  "target_vocabulary": "SNOMED",
  "mapping_type": "direct"
}
```

<Note>
  The `source_concepts` parameter expects **OMOP concept IDs** (internal database IDs), NOT vocabulary-specific codes.
  If you have vocabulary codes (e.g., ICD-10 code "E11.9"), use the `source_codes` parameter instead,
  or first look up the OMOP concept ID using `/v1/concepts/by-code/{vocabulary}/{code}`.
</Note>

## Related Endpoints

* [Batch Map Concepts](/api-reference/mappings/batch-map-concepts) - Batch mapping operations
* [Get Concept Mappings](/api-reference/mappings/get-concept-mappings) - Get mappings for a specific concept
* [Validate Mappings](/api-reference/mappings/validate-mappings) - Validate mapping accuracy