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

# Get Mapping Coverage

> Analyze mapping coverage between a source and target OMOP vocabulary - quantify how many concepts translate across SNOMED, ICD-10, LOINC, and RxNorm.

## Overview

This endpoint analyzes mapping coverage between two vocabularies, providing domain-level breakdown and identifying unmapped concepts. Useful for understanding interoperability between vocabulary pairs.

## Query Parameters

<ParamField query="source_vocabulary" type="string" required>
  Source vocabulary ID to analyze mappings from

  <br />

  **Example:** `SNOMED`
</ParamField>

<ParamField query="target_vocabulary" type="string" required>
  Target vocabulary ID to analyze mappings to

  <br />

  **Example:** `ICD10CM`
</ParamField>

<ParamField query="domain_ids" type="string">
  Comma-separated domain IDs to filter the analysis

  <br />

  **Example:** `Condition,Drug`
</ParamField>

<ParamField query="vocab_release" type="string">
  Specific vocabulary release version (e.g., "2025.1")
</ParamField>

## Response

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

<ResponseField name="data" type="object" required>
  Coverage analysis results

  <Expandable title="data">
    <ResponseField name="source_vocabulary" type="string">
      Source vocabulary ID analyzed
    </ResponseField>

    <ResponseField name="target_vocabulary" type="string">
      Target vocabulary ID analyzed
    </ResponseField>

    <ResponseField name="domain_coverage" type="array">
      Coverage breakdown by domain

      <Expandable title="domain_coverage">
        <ResponseField name="domain_id" type="string">
          Domain identifier
        </ResponseField>

        <ResponseField name="domain_name" type="string">
          Human-readable domain name
        </ResponseField>

        <ResponseField name="source_concepts" type="integer">
          Number of source concepts in this domain
        </ResponseField>

        <ResponseField name="mapped_concepts" type="integer">
          Number of concepts with mappings to target vocabulary
        </ResponseField>

        <ResponseField name="coverage_percentage" type="number">
          Percentage of concepts with mappings (0-100)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="overall_coverage" type="number">
      Overall coverage percentage across all domains (0-100)
    </ResponseField>

    <ResponseField name="unmapped_concepts" type="array">
      Sample of concepts without mappings (up to 100)

      <Expandable title="unmapped_concepts">
        <ResponseField name="concept_id" type="integer">
          Concept identifier
        </ResponseField>

        <ResponseField name="concept_name" type="string">
          Concept name
        </ResponseField>

        <ResponseField name="domain_id" type="string">
          Domain of the concept
        </ResponseField>

        <ResponseField name="reason" type="string">
          Reason for no mapping
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object" required>
  Response metadata and API information

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

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp of the response
    </ResponseField>

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

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.omophub.com/v1/mappings/coverage?source_vocabulary=SNOMED&target_vocabulary=ICD10CM" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.omophub.com/v1/mappings/coverage?source_vocabulary=SNOMED&target_vocabulary=ICD10CM', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const result = await response.json();
  console.log(`Overall coverage: ${result.data.overall_coverage}%`);

  result.data.domain_coverage.forEach(domain => {
    console.log(`${domain.domain_name}: ${domain.coverage_percentage}% (${domain.mapped_concepts}/${domain.source_concepts})`);
  });
  ```

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

  response = requests.get(
      "https://api.omophub.com/v1/mappings/coverage",
      params={
          "source_vocabulary": "SNOMED",
          "target_vocabulary": "ICD10CM"
      },
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )

  result = response.json()
  print(f"Overall coverage: {result['data']['overall_coverage']}%")

  for domain in result['data']['domain_coverage']:
      print(f"{domain['domain_name']}: {domain['coverage_percentage']}%")
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "source_vocabulary": "SNOMED",
      "target_vocabulary": "ICD10CM",
      "domain_coverage": [
        {
          "domain_id": "Condition",
          "domain_name": "Condition",
          "source_concepts": 234567,
          "mapped_concepts": 178234,
          "coverage_percentage": 75.9
        },
        {
          "domain_id": "Procedure",
          "domain_name": "Procedure",
          "source_concepts": 89234,
          "mapped_concepts": 45678,
          "coverage_percentage": 51.2
        },
        {
          "domain_id": "Observation",
          "domain_name": "Observation",
          "source_concepts": 45678,
          "mapped_concepts": 12345,
          "coverage_percentage": 27.0
        }
      ],
      "overall_coverage": 65.5,
      "unmapped_concepts": [
        {
          "concept_id": 4087682,
          "concept_name": "Finding related to ability to move",
          "domain_id": "Condition",
          "reason": "No direct mapping"
        },
        {
          "concept_id": 4273391,
          "concept_name": "Coronary artery bypass graft",
          "domain_id": "Procedure",
          "reason": "No direct mapping"
        }
      ]
    },
    "meta": {
      "request_id": "req_coverage_abc123",
      "timestamp": "2024-12-22T10:00:00Z",
      "vocab_release": "2025.2"
    }
  }
  ```
</ResponseExample>

## Usage Examples

### Basic Coverage Analysis

Analyze coverage from SNOMED to ICD-10-CM:

```javascript theme={null}
const coverage = await fetch('/v1/mappings/coverage?source_vocabulary=SNOMED&target_vocabulary=ICD10CM');
```

### Filter by Domain

Analyze coverage for specific domains only:

```javascript theme={null}
const conditionCoverage = await fetch('/v1/mappings/coverage?source_vocabulary=SNOMED&target_vocabulary=ICD10CM&domain_ids=Condition,Procedure');
```

### Use Specific Vocabulary Version

Analyze coverage for a specific vocabulary release:

```javascript theme={null}
const coverage = await fetch('/v1/mappings/coverage?source_vocabulary=SNOMED&target_vocabulary=ICD10CM&vocab_release=2025.1');
```

## Related Endpoints

* [Get Concept Mappings](/api-reference/mappings/get-concept-mappings) - Mappings for specific concepts
* [Get Mapping Quality](/api-reference/mappings/get-mapping-quality) - Quality metrics between vocabularies
* [Map Concepts](/api-reference/mappings/map-concepts) - Map concepts to a target vocabulary

## Notes

* Both `source_vocabulary` and `target_vocabulary` are required parameters
* The `unmapped_concepts` array contains a sample of up to 100 unmapped concepts
* Coverage percentages are calculated based on valid, non-deprecated concepts
* Use `domain_ids` to focus analysis on specific medical domains