Skip to main content
curl -X GET "https://api.omophub.com/v1/mappings/quality?domain_ids=Condition,Drug&include_detailed_metrics=true&include_recommendations=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "quality_overview": {
    "total_mappings_analyzed": 4578923,
    "mappings_with_quality_data": 3456789,
    "overall_average_confidence": 0.847,
    "overall_quality_rating": "good",
    "high_quality_percentage": 72.3,
    "validated_percentage": 68.9,
    "disputed_percentage": 2.7
  },
  "quality_by_vocabulary_pair": {
    "SNOMED": {
      "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
      "target_vocabularies": {
        "ICD10CM": {
          "target_vocabulary_name": "International Classification of Diseases, Tenth Revision, Clinical Modification",
          "total_mappings": 156789,
          "average_confidence": 0.923,
          "median_confidence": 0.950,
          "confidence_std_dev": 0.087,
          "equivalence_distribution": {
            "exact": 89234,
            "broader": 45678,
            "narrower": 12345,
            "related": 9532
          },
          "validation_rate": 0.847,
          "quality_rating": "excellent",
          "primary_use_cases": ["billing", "quality_reporting", "clinical_documentation"]
        },
        "HCPCS": {
          "target_vocabulary_name": "Healthcare Common Procedure Coding System",
          "total_mappings": 67890,
          "average_confidence": 0.756,
          "median_confidence": 0.780,
          "confidence_std_dev": 0.145,
          "equivalence_distribution": {
            "exact": 23456,
            "broader": 34567,
            "narrower": 6789,
            "related": 3078
          },
          "validation_rate": 0.623,
          "quality_rating": "good",
          "primary_use_cases": ["billing", "procedure_coding"]
        }
      },
      "overall_outgoing_quality": 0.875
    }
  },
  "quality_by_domain": {
    "Condition": {
      "domain_name": "Condition",
      "total_mappings": 2847562,
      "average_confidence": 0.891,
      "quality_distribution": {
        "excellent": 1456789,
        "good": 987654,
        "moderate": 345678,
        "poor": 57441
      },
      "most_reliable_vocabulary_pairs": [
        "SNOMED → ICD10CM",
        "ICD10CM → SNOMED", 
        "SNOMED → ICD10"
      ],
      "least_reliable_vocabulary_pairs": [
        "Read → ICPC2",
        "Local → Standard"
      ],
      "quality_challenges": [
        "Complex conditions often map to broader categories",
        "Regional terminology variations affect consistency",
        "Rare diseases have limited mapping coverage"
      ]
    },
    "Drug": {
      "domain_name": "Drug",
      "total_mappings": 987654,
      "average_confidence": 0.823,
      "quality_distribution": {
        "excellent": 456789,
        "good": 345678,
        "moderate": 123456,
        "poor": 61731
      },
      "most_reliable_vocabulary_pairs": [
        "RxNorm → NDC",
        "NDC → RxNorm"
      ],
      "least_reliable_vocabulary_pairs": [
        "SNOMED → RxNorm",
        "Local drug codes → RxNorm"
      ],
      "quality_challenges": [
        "Generic vs brand name mapping complexity",
        "Dosage form variations affect precision",
        "Discontinued medications create gaps"
      ]
    }
  },
  "quality_metrics": {
    "confidence_score_distribution": {
      "histogram_bins": [
        {"min": 0.0, "max": 0.1, "count": 12456},
        {"min": 0.1, "max": 0.2, "count": 23456},
        {"min": 0.8, "max": 0.9, "count": 456789},
        {"min": 0.9, "max": 1.0, "count": 678901}
      ],
      "percentiles": {
        "25": 0.734,
        "50": 0.847,
        "75": 0.923,
        "95": 0.978
      },
      "skewness": -0.342,
      "kurtosis": 2.156
    },
    "semantic_similarity_analysis": {
      "average_similarity": 0.823,
      "similarity_confidence_correlation": 0.756,
      "low_similarity_high_confidence": 23456,
      "high_similarity_low_confidence": 12345
    },
    "mapping_source_analysis": {
      "official_mappings": {
        "average_confidence": 0.912,
        "total_count": 2345678,
        "validation_rate": 0.923
      },
      "community_mappings": {
        "average_confidence": 0.734,
        "total_count": 456789,
        "validation_rate": 0.456
      },
      "algorithmic_mappings": {
        "average_confidence": 0.678,
        "total_count": 567890,
        "validation_rate": 0.234
      }
    }
  },
  "quality_outliers": {
    "low_quality_outliers": [
      {
        "source_concept_id": 12345,
        "target_concept_id": 67890,
        "confidence_score": 0.123,
        "outlier_reason": "Very low confidence despite official mapping",
        "potential_issues": [
          "Semantic mismatch",
          "Outdated mapping relationship"
        ]
      }
    ],
    "outlier_patterns": [
      "Algorithmic mappings between distant concept classes",
      "Legacy mappings not updated with vocabulary revisions",
      "Cross-domain mappings with semantic drift"
    ]
  },
  "recommendations": [
    {
      "recommendation_type": "validation_review",
      "title": "Review disputed SNOMED to HCPCS mappings",
      "description": "Systematic review of 2,847 disputed mappings between SNOMED procedures and HCPCS codes to improve validation rate",
      "priority": "high",
      "expected_improvement": "Increase HCPCS mapping quality by 15-20%",
      "affected_vocabulary_pairs": ["SNOMED → HCPCS"],
      "implementation_effort": "moderate"
    },
    {
      "recommendation_type": "algorithmic_improvement", 
      "title": "Enhance semantic similarity algorithms for drug mappings",
      "description": "Improve algorithmic mapping quality between drug vocabularies using enhanced semantic similarity models",
      "priority": "medium",
      "expected_improvement": "Increase drug domain confidence by 10%",
      "affected_vocabulary_pairs": ["RxNorm → NDC", "SNOMED → RxNorm"],
      "implementation_effort": "high"
    }
  ]
  },
  "meta": {
    "request_id": "req_quality_analysis_234567",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2",
    "analysis_scope": {
      "vocabularies_included": 23,
      "domains_analyzed": 15,
      "mapping_relationships_analyzed": 4578923
    },
    "confidence_calculation_method": "weighted_semantic_similarity_with_validation"
  }
}
This endpoint provides comprehensive analysis of mapping quality throughout the vocabulary ecosystem, essential for understanding the reliability of cross-vocabulary translations, identifying high-confidence mappings, and assessing the trustworthiness of mapping relationships for clinical and operational use.

​
Query Parameters

​
source_vocabularies
string
Filter analysis to specific source vocabularies
Example: SNOMED,ICD10CM,RxNorm
​
target_vocabularies
string
Filter analysis to specific target vocabularies
Example: ICD10CM,HCPCS,NDC
​
domain_ids
string
Focus analysis on specific domains
Example: Condition,Drug,Procedure
​
concept_class_ids
string
Focus analysis on specific concept classes
Example: Clinical Finding,Procedure,Ingredient
​
equivalence_types
string
Filter by mapping equivalence types
Example: exact,broader,narrower,related
​
validation_status
string
Filter by mapping validation status
Options: validated, pending, disputed, deprecated
​
mapping_sources
string
Filter by mapping source types
Example: official,community,algorithmic,manual
​
confidence_threshold
number
default:"0.0"
Minimum confidence score for inclusion (0-1)
​
include_detailed_metrics
boolean
default:"true"
Include detailed quality metrics and distributions
​
include_outliers
boolean
default:"false"
Include analysis of quality outliers and anomalies
​
include_trends
boolean
default:"false"
Include historical quality trends
​
include_recommendations
boolean
default:"false"
Include recommendations for quality improvement
​
sample_size
integer
Maximum number of mappings to analyze for detailed metrics
Default: No limit

​
Response

​
quality_overview
object
High-level summary of mapping quality
​
quality_by_vocabulary_pair
object
Quality metrics for each vocabulary pair
​
quality_by_domain
object
Quality analysis by medical domain
​
quality_metrics
object
Detailed quality metrics and distributions
​
quality_outliers
object
Analysis of quality outliers and anomalies (when include_outliers=true)
​
quality_trends
object
Historical quality trends (when include_trends=true)
​
recommendations
array
Recommendations for quality improvement (when include_recommendations=true)
​
meta
object
Analysis metadata and processing information
curl -X GET "https://api.omophub.com/v1/mappings/quality?domain_ids=Condition,Drug&include_detailed_metrics=true&include_recommendations=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "quality_overview": {
    "total_mappings_analyzed": 4578923,
    "mappings_with_quality_data": 3456789,
    "overall_average_confidence": 0.847,
    "overall_quality_rating": "good",
    "high_quality_percentage": 72.3,
    "validated_percentage": 68.9,
    "disputed_percentage": 2.7
  },
  "quality_by_vocabulary_pair": {
    "SNOMED": {
      "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
      "target_vocabularies": {
        "ICD10CM": {
          "target_vocabulary_name": "International Classification of Diseases, Tenth Revision, Clinical Modification",
          "total_mappings": 156789,
          "average_confidence": 0.923,
          "median_confidence": 0.950,
          "confidence_std_dev": 0.087,
          "equivalence_distribution": {
            "exact": 89234,
            "broader": 45678,
            "narrower": 12345,
            "related": 9532
          },
          "validation_rate": 0.847,
          "quality_rating": "excellent",
          "primary_use_cases": ["billing", "quality_reporting", "clinical_documentation"]
        },
        "HCPCS": {
          "target_vocabulary_name": "Healthcare Common Procedure Coding System",
          "total_mappings": 67890,
          "average_confidence": 0.756,
          "median_confidence": 0.780,
          "confidence_std_dev": 0.145,
          "equivalence_distribution": {
            "exact": 23456,
            "broader": 34567,
            "narrower": 6789,
            "related": 3078
          },
          "validation_rate": 0.623,
          "quality_rating": "good",
          "primary_use_cases": ["billing", "procedure_coding"]
        }
      },
      "overall_outgoing_quality": 0.875
    }
  },
  "quality_by_domain": {
    "Condition": {
      "domain_name": "Condition",
      "total_mappings": 2847562,
      "average_confidence": 0.891,
      "quality_distribution": {
        "excellent": 1456789,
        "good": 987654,
        "moderate": 345678,
        "poor": 57441
      },
      "most_reliable_vocabulary_pairs": [
        "SNOMED → ICD10CM",
        "ICD10CM → SNOMED", 
        "SNOMED → ICD10"
      ],
      "least_reliable_vocabulary_pairs": [
        "Read → ICPC2",
        "Local → Standard"
      ],
      "quality_challenges": [
        "Complex conditions often map to broader categories",
        "Regional terminology variations affect consistency",
        "Rare diseases have limited mapping coverage"
      ]
    },
    "Drug": {
      "domain_name": "Drug",
      "total_mappings": 987654,
      "average_confidence": 0.823,
      "quality_distribution": {
        "excellent": 456789,
        "good": 345678,
        "moderate": 123456,
        "poor": 61731
      },
      "most_reliable_vocabulary_pairs": [
        "RxNorm → NDC",
        "NDC → RxNorm"
      ],
      "least_reliable_vocabulary_pairs": [
        "SNOMED → RxNorm",
        "Local drug codes → RxNorm"
      ],
      "quality_challenges": [
        "Generic vs brand name mapping complexity",
        "Dosage form variations affect precision",
        "Discontinued medications create gaps"
      ]
    }
  },
  "quality_metrics": {
    "confidence_score_distribution": {
      "histogram_bins": [
        {"min": 0.0, "max": 0.1, "count": 12456},
        {"min": 0.1, "max": 0.2, "count": 23456},
        {"min": 0.8, "max": 0.9, "count": 456789},
        {"min": 0.9, "max": 1.0, "count": 678901}
      ],
      "percentiles": {
        "25": 0.734,
        "50": 0.847,
        "75": 0.923,
        "95": 0.978
      },
      "skewness": -0.342,
      "kurtosis": 2.156
    },
    "semantic_similarity_analysis": {
      "average_similarity": 0.823,
      "similarity_confidence_correlation": 0.756,
      "low_similarity_high_confidence": 23456,
      "high_similarity_low_confidence": 12345
    },
    "mapping_source_analysis": {
      "official_mappings": {
        "average_confidence": 0.912,
        "total_count": 2345678,
        "validation_rate": 0.923
      },
      "community_mappings": {
        "average_confidence": 0.734,
        "total_count": 456789,
        "validation_rate": 0.456
      },
      "algorithmic_mappings": {
        "average_confidence": 0.678,
        "total_count": 567890,
        "validation_rate": 0.234
      }
    }
  },
  "quality_outliers": {
    "low_quality_outliers": [
      {
        "source_concept_id": 12345,
        "target_concept_id": 67890,
        "confidence_score": 0.123,
        "outlier_reason": "Very low confidence despite official mapping",
        "potential_issues": [
          "Semantic mismatch",
          "Outdated mapping relationship"
        ]
      }
    ],
    "outlier_patterns": [
      "Algorithmic mappings between distant concept classes",
      "Legacy mappings not updated with vocabulary revisions",
      "Cross-domain mappings with semantic drift"
    ]
  },
  "recommendations": [
    {
      "recommendation_type": "validation_review",
      "title": "Review disputed SNOMED to HCPCS mappings",
      "description": "Systematic review of 2,847 disputed mappings between SNOMED procedures and HCPCS codes to improve validation rate",
      "priority": "high",
      "expected_improvement": "Increase HCPCS mapping quality by 15-20%",
      "affected_vocabulary_pairs": ["SNOMED → HCPCS"],
      "implementation_effort": "moderate"
    },
    {
      "recommendation_type": "algorithmic_improvement", 
      "title": "Enhance semantic similarity algorithms for drug mappings",
      "description": "Improve algorithmic mapping quality between drug vocabularies using enhanced semantic similarity models",
      "priority": "medium",
      "expected_improvement": "Increase drug domain confidence by 10%",
      "affected_vocabulary_pairs": ["RxNorm → NDC", "SNOMED → RxNorm"],
      "implementation_effort": "high"
    }
  ]
  },
  "meta": {
    "request_id": "req_quality_analysis_234567",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2",
    "analysis_scope": {
      "vocabularies_included": 23,
      "domains_analyzed": 15,
      "mapping_relationships_analyzed": 4578923
    },
    "confidence_calculation_method": "weighted_semantic_similarity_with_validation"
  }
}

​
Usage Examples

​
Overall Quality Assessment

Get comprehensive quality overview: 
const quality = await fetch('/v1/mappings/quality');

​
Domain-Specific Quality Analysis

Analyze quality for clinical domains: 
const clinicalQuality = await fetch('/v1/mappings/quality?domain_ids=Condition,Drug,Procedure&include_detailed_metrics=true');

​
High-Confidence Mappings Only

Analyze only high-quality mappings: 
const highQuality = await fetch('/v1/mappings/quality?confidence_threshold=0.8&include_outliers=true');

​
Vocabulary Pair Quality

Focus on specific vocabulary relationships: 
const vocabQuality = await fetch('/v1/mappings/quality?source_vocabularies=SNOMED&target_vocabularies=ICD10CM,HCPCS&include_recommendations=true');

​
Quality Trend Analysis

Get historical quality trends: 
const trendAnalysis = await fetch('/v1/mappings/quality?include_trends=true&include_recommendations=true');

​
Notes

  • Quality analysis requires substantial computational resources for large datasets
  • Confidence scores are calculated using multiple factors including semantic similarity and validation status
  • Official mappings generally have higher quality than algorithmic or community mappings
  • Quality can vary significantly between vocabulary pairs and domains
  • Disputed mappings may indicate areas needing expert review
  • Quality trends help identify improvement or degradation over time
  • Outlier analysis reveals mappings that may need special attention
  • Quality thresholds help focus on the most reliable mappings for production use
⌘I