Skip to main content
curl -X GET "https://api.omophub.com/v1/mappings/vocabularies/SNOMED/ICD10CM?domain_ids=Condition&include_statistics=true&include_mapping_quality=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
{
  "success": true,
  "data": {
    "vocabulary_pair": {
      "source_vocabulary": {
        "vocabulary_id": "SNOMED",
        "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
        "vocabulary_reference": "http://www.snomed.org/",
        "vocabulary_version": "20240301",
        "total_concepts": 387421
      },
      "target_vocabulary": {
        "vocabulary_id": "ICD10CM",
        "vocabulary_name": "International Classification of Diseases, Tenth Revision, Clinical Modification",
        "vocabulary_reference": "https://www.cdc.gov/nchs/icd/icd10cm.htm",
        "vocabulary_version": "2024",
        "total_concepts": 98234
      },
      "mapping_relationship": "SNOMED CT clinical concepts mapped to ICD-10-CM billing codes for US healthcare"
    },
    "mappings": [
      {
        "mapping_id": "map_201826_45757292",
        "source_concept": {
          "concept_id": 201826,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        "target_concept": {
          "concept_id": 45757292,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "E11",
          "domain_id": "Condition",
          "concept_class_id": "3-char billing code",
          "standard_concept": "S"
        },
        "mapping_type": "Maps to",
        "mapping_quality": {
          "confidence_score": 0.98,
          "equivalence_type": "exact",
          "semantic_similarity": 0.95,
          "mapping_source": "official",
          "validation_status": "validated"
        },
        "valid_start_date": "2016-10-01T00:00:00Z",
        "valid_end_date": "2099-12-31T00:00:00Z"
      },
      {
        "mapping_id": "map_320128_44784217",
        "source_concept": {
          "concept_id": 320128,
          "concept_name": "Essential hypertension",
          "concept_code": "59621000",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        "target_concept": {
          "concept_id": 44784217,
          "concept_name": "Essential hypertension",
          "concept_code": "I10",
          "domain_id": "Condition",
          "concept_class_id": "3-char billing code",
          "standard_concept": "S"
        },
        "mapping_type": "Maps to",
        "mapping_quality": {
          "confidence_score": 0.97,
          "equivalence_type": "exact",
          "semantic_similarity": 0.94,
          "mapping_source": "official",
          "validation_status": "validated"
        },
        "valid_start_date": "2016-10-01T00:00:00Z",
        "valid_end_date": "2099-12-31T00:00:00Z"
      }
    ],
    "mapping_statistics": {
      "total_mappings": 156789,
      "coverage_analysis": {
        "source_coverage": {
          "concepts_with_mappings": 234567,
          "concepts_without_mappings": 152854,
          "coverage_percentage": 60.5,
          "domain_coverage": {
            "Condition": 78.2,
            "Procedure": 45.7,
            "Observation": 23.1
          }
        },
        "target_coverage": {
          "concepts_with_mappings": 87432,
          "concepts_without_mappings": 10802,
          "coverage_percentage": 89.0
        }
      },
      "quality_distribution": {
        "equivalence_type_counts": {
          "exact": 98765,
          "broader": 34567,
          "narrower": 15234,
          "related": 8223
        },
        "confidence_score_ranges": {
          "0.9-1.0": 78543,
          "0.8-0.9": 45678,
          "0.7-0.8": 23456,
          "0.6-0.7": 9112
        },
        "validation_status_counts": {
          "validated": 134567,
          "pending": 15678,
          "disputed": 3456,
          "deprecated": 3088
        },
        "average_confidence_score": 0.874
      },
      "domain_distribution": {
        "Condition": 89234,
        "Procedure": 45678,
        "Observation": 12456,
        "Measurement": 6789,
        "Device": 2632
      },
      "concept_class_distribution": {
        "Clinical Finding": 67890,
        "Procedure": 34567,
        "3-char billing code": 23456,
        "4-char billing code": 12345,
        "Observable Entity": 8765
      },
      "temporal_analysis": {
        "oldest_mapping_date": "2016-10-01T00:00:00Z",
        "newest_mapping_date": "2024-03-15T00:00:00Z",
        "mappings_by_year": {
          "2016": 98765,
          "2017": 12345,
          "2018": 8976,
          "2019": 15432,
          "2020": 7654
        },
        "recent_updates": 3456
      }
    },
    "mapping_gaps": {
      "source_gaps": {
        "total_unmapped_concepts": 152854,
        "unmapped_by_domain": {
          "Observation": 78432,
          "Measurement": 34567,
          "Condition": 23456,
          "Procedure": 16399
        },
        "unmapped_by_concept_class": {
          "Observable Entity": 56789,
          "Clinical Finding": 34567,
          "Procedure": 23456
        },
        "sample_unmapped_concepts": [
          {
            "concept_id": 4567890,
            "concept_name": "Blood pressure taking",
            "concept_code": "75367002",
            "domain_id": "Observation"
          }
        ],
        "gap_patterns": [
          "Many observational procedures lack ICD-10-CM equivalents",
          "Complex procedures often map to broader categories",
          "Specialized measurements have limited billing code coverage"
        ]
      },
      "recommendations": [
        "Consider using HCPCS for unmapped procedures",
        "Review observation domain mappings with clinical experts",
        "Implement custom mapping rules for specialized concepts"
      ]
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 1000,
      "total_items": 156789,
      "total_pages": 157,
      "has_next": true,
      "has_previous": false
    },
    "request_id": "req_vocab_mappings_789012",
    "timestamp": "2024-12-22T10:30:00Z",
    "vocab_release": "2025.2"
  }
}
This endpoint provides bulk access to all mapping relationships between two vocabularies, essential for data integration, terminology harmonization, and cross-system interoperability. It’s particularly useful for understanding mapping coverage and implementing vocabulary translation services.

Path Parameters

source_vocabulary_id
string
required
The source vocabulary identifier
Example: SNOMED, ICD10CM, RxNorm
target_vocabulary_id
string
required
The target vocabulary identifier
Example: ICD10CM, ICD10, HCPCS

Query Parameters

domain_ids
string
Filter mappings to specific domains
Example: Condition,Drug,Procedure
concept_class_ids
string
Filter mappings to specific concept classes
Example: Clinical Finding,Procedure
mapping_types
string
Filter by specific mapping relationship types
Default: Maps to,Mapped from
Example: Maps to,Maps to value
standard_concepts_only
string
default:"both"
Filter by standard concept status
Options: source, target, both, either, none
include_mapping_quality
boolean
default:"false"
Include mapping quality scores and metadata
include_statistics
boolean
default:"false"
Include statistical analysis of the mapping set
include_gaps
boolean
default:"false"
Include analysis of unmapped concepts (gaps)
quality_threshold
number
Minimum mapping quality score (0-1)
Example: 0.8
equivalence_types
string
Filter by mapping equivalence types
Example: exact,broader,narrower
active_only
boolean
default:"true"
Only include mappings between active concepts
sort_by
string
default:"source_concept_id"
Sort mappings by specified field
Options: source_concept_id, target_concept_id, source_concept_name, mapping_quality
sort_order
string
default:"asc"
Sort order for mappings
Options: asc, desc
page_size
integer
default:"1000"
Number of mappings to return per page (max 5000)
page
integer
default:"1"
Page number for pagination (1-based)

Response

vocabulary_pair
object
Information about the source and target vocabularies
mappings
array
Array of mapping relationships between the vocabularies
mapping_statistics
object
Statistical analysis of the vocabulary mappings (when include_statistics=true)
mapping_gaps
object
Analysis of unmapped concepts (when include_gaps=true)
meta
object
Response metadata and pagination information
curl -X GET "https://api.omophub.com/v1/mappings/vocabularies/SNOMED/ICD10CM?domain_ids=Condition&include_statistics=true&include_mapping_quality=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
{
  "success": true,
  "data": {
    "vocabulary_pair": {
      "source_vocabulary": {
        "vocabulary_id": "SNOMED",
        "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
        "vocabulary_reference": "http://www.snomed.org/",
        "vocabulary_version": "20240301",
        "total_concepts": 387421
      },
      "target_vocabulary": {
        "vocabulary_id": "ICD10CM",
        "vocabulary_name": "International Classification of Diseases, Tenth Revision, Clinical Modification",
        "vocabulary_reference": "https://www.cdc.gov/nchs/icd/icd10cm.htm",
        "vocabulary_version": "2024",
        "total_concepts": 98234
      },
      "mapping_relationship": "SNOMED CT clinical concepts mapped to ICD-10-CM billing codes for US healthcare"
    },
    "mappings": [
      {
        "mapping_id": "map_201826_45757292",
        "source_concept": {
          "concept_id": 201826,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        "target_concept": {
          "concept_id": 45757292,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "E11",
          "domain_id": "Condition",
          "concept_class_id": "3-char billing code",
          "standard_concept": "S"
        },
        "mapping_type": "Maps to",
        "mapping_quality": {
          "confidence_score": 0.98,
          "equivalence_type": "exact",
          "semantic_similarity": 0.95,
          "mapping_source": "official",
          "validation_status": "validated"
        },
        "valid_start_date": "2016-10-01T00:00:00Z",
        "valid_end_date": "2099-12-31T00:00:00Z"
      },
      {
        "mapping_id": "map_320128_44784217",
        "source_concept": {
          "concept_id": 320128,
          "concept_name": "Essential hypertension",
          "concept_code": "59621000",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        "target_concept": {
          "concept_id": 44784217,
          "concept_name": "Essential hypertension",
          "concept_code": "I10",
          "domain_id": "Condition",
          "concept_class_id": "3-char billing code",
          "standard_concept": "S"
        },
        "mapping_type": "Maps to",
        "mapping_quality": {
          "confidence_score": 0.97,
          "equivalence_type": "exact",
          "semantic_similarity": 0.94,
          "mapping_source": "official",
          "validation_status": "validated"
        },
        "valid_start_date": "2016-10-01T00:00:00Z",
        "valid_end_date": "2099-12-31T00:00:00Z"
      }
    ],
    "mapping_statistics": {
      "total_mappings": 156789,
      "coverage_analysis": {
        "source_coverage": {
          "concepts_with_mappings": 234567,
          "concepts_without_mappings": 152854,
          "coverage_percentage": 60.5,
          "domain_coverage": {
            "Condition": 78.2,
            "Procedure": 45.7,
            "Observation": 23.1
          }
        },
        "target_coverage": {
          "concepts_with_mappings": 87432,
          "concepts_without_mappings": 10802,
          "coverage_percentage": 89.0
        }
      },
      "quality_distribution": {
        "equivalence_type_counts": {
          "exact": 98765,
          "broader": 34567,
          "narrower": 15234,
          "related": 8223
        },
        "confidence_score_ranges": {
          "0.9-1.0": 78543,
          "0.8-0.9": 45678,
          "0.7-0.8": 23456,
          "0.6-0.7": 9112
        },
        "validation_status_counts": {
          "validated": 134567,
          "pending": 15678,
          "disputed": 3456,
          "deprecated": 3088
        },
        "average_confidence_score": 0.874
      },
      "domain_distribution": {
        "Condition": 89234,
        "Procedure": 45678,
        "Observation": 12456,
        "Measurement": 6789,
        "Device": 2632
      },
      "concept_class_distribution": {
        "Clinical Finding": 67890,
        "Procedure": 34567,
        "3-char billing code": 23456,
        "4-char billing code": 12345,
        "Observable Entity": 8765
      },
      "temporal_analysis": {
        "oldest_mapping_date": "2016-10-01T00:00:00Z",
        "newest_mapping_date": "2024-03-15T00:00:00Z",
        "mappings_by_year": {
          "2016": 98765,
          "2017": 12345,
          "2018": 8976,
          "2019": 15432,
          "2020": 7654
        },
        "recent_updates": 3456
      }
    },
    "mapping_gaps": {
      "source_gaps": {
        "total_unmapped_concepts": 152854,
        "unmapped_by_domain": {
          "Observation": 78432,
          "Measurement": 34567,
          "Condition": 23456,
          "Procedure": 16399
        },
        "unmapped_by_concept_class": {
          "Observable Entity": 56789,
          "Clinical Finding": 34567,
          "Procedure": 23456
        },
        "sample_unmapped_concepts": [
          {
            "concept_id": 4567890,
            "concept_name": "Blood pressure taking",
            "concept_code": "75367002",
            "domain_id": "Observation"
          }
        ],
        "gap_patterns": [
          "Many observational procedures lack ICD-10-CM equivalents",
          "Complex procedures often map to broader categories",
          "Specialized measurements have limited billing code coverage"
        ]
      },
      "recommendations": [
        "Consider using HCPCS for unmapped procedures",
        "Review observation domain mappings with clinical experts",
        "Implement custom mapping rules for specialized concepts"
      ]
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 1000,
      "total_items": 156789,
      "total_pages": 157,
      "has_next": true,
      "has_previous": false
    },
    "request_id": "req_vocab_mappings_789012",
    "timestamp": "2024-12-22T10:30:00Z",
    "vocab_release": "2025.2"
  }
}

Usage Examples

Basic Vocabulary Mappings

Get all mappings between two vocabularies:
const mappings = await fetch('/v1/mappings/vocabularies/SNOMED/ICD10CM');

High-Quality Condition Mappings

Get high-quality mappings for conditions:
const qualityMappings = await fetch('/v1/mappings/vocabularies/SNOMED/ICD10CM?domain_ids=Condition&quality_threshold=0.8&include_mapping_quality=true');

Comprehensive Mapping Analysis

Get detailed statistics and gap analysis:
const analysis = await fetch('/v1/mappings/vocabularies/SNOMED/ICD10CM?include_statistics=true&include_gaps=true&include_mapping_quality=true');

Drug Mappings

Get mappings between drug vocabularies:
const drugMappings = await fetch('/v1/mappings/vocabularies/RxNorm/NDC?domain_ids=Drug&equivalence_types=exact');

Standard Concept Mappings Only

Get mappings involving only standard concepts:
const standardMappings = await fetch('/v1/mappings/vocabularies/SNOMED/HCPCS?standard_concepts_only=both&domain_ids=Procedure');

Notes

  • Large vocabulary pairs may return many thousands of mappings - use pagination appropriately
  • Coverage analysis helps identify gaps in cross-vocabulary translation capabilities
  • Quality scores help prioritize the most reliable mappings for production use
  • Gap analysis reveals unmapped concepts that may require custom mapping rules
  • Temporal analysis shows mapping evolution and maintenance patterns
  • Some vocabulary pairs have asymmetric coverage (better mapping in one direction)
  • Official mappings are generally more reliable than algorithmic or community mappings
  • Domain and concept class filtering can significantly improve query performance
I