Skip to main content
curl -X GET "https://api.omophub.com/v1/concepts/201826/mappings?target_vocabularies=ICD10CM,ICD10&include_mapping_quality=true&include_synonyms=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "success": true,
  "data": {
    "source_concept": {
      "concept_id": 201826,
      "concept_name": "Type 2 diabetes mellitus",
      "concept_code": "44054006",
      "vocabulary_id": "SNOMED",
      "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    },
    "mappings": [
      {
        "mapping_id": "map_201826_45757292",
        "mapping_type": "Maps to",
        "direction": "outgoing",
        "target_concept": {
          "concept_id": 45757292,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "E11",
          "vocabulary_id": "ICD10CM",
          "vocabulary_name": "International Classification of Diseases, Tenth Revision, Clinical Modification",
          "domain_id": "Condition",
          "concept_class_id": "3-char billing code",
          "standard_concept": "S",
          "synonyms": [
            {
              "concept_synonym_name": "Type II diabetes mellitus",
              "language_concept_id": 4180186,
              "language_concept_name": "English"
            },
            {
              "concept_synonym_name": "Adult-onset diabetes",
              "language_concept_id": 4180186,
              "language_concept_name": "English"
            }
          ],
          "valid_start_date": "2016-10-01",
          "valid_end_date": "2099-12-31"
        },
        "mapping_quality": {
          "confidence_score": 0.98,
          "equivalence_type": "exact",
          "semantic_similarity": 0.95,
          "mapping_source": "official",
          "validation_status": "validated",
          "last_reviewed_date": "2024-01-15"
        },
        "mapping_context": {
          "use_case": "billing",
          "geographic_scope": ["US"],
          "temporal_scope": {
            "start_date": "2016-10-01",
            "end_date": null
          },
          "mapping_notes": "Official crosswalk mapping for ICD-10-CM billing purposes",
          "cross_walk_source": "CMS ICD-10-CM Official Guidelines"
        },
        "valid_start_date": "2016-10-01",
        "valid_end_date": "2099-12-31"
      },
      {
        "mapping_id": "map_201826_4087682",
        "mapping_type": "Maps to",
        "direction": "outgoing",
        "target_concept": {
          "concept_id": 4087682,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "E11.9",
          "vocabulary_id": "ICD10",
          "vocabulary_name": "International Classification of Diseases, Tenth Revision",
          "domain_id": "Condition",
          "concept_class_id": "ICD10 code",
          "standard_concept": "S",
          "valid_start_date": "1990-01-01",
          "valid_end_date": "2099-12-31"
        },
        "mapping_quality": {
          "confidence_score": 0.94,
          "equivalence_type": "exact",
          "semantic_similarity": 0.92,
          "mapping_source": "official",
          "validation_status": "validated",
          "last_reviewed_date": "2023-08-20"
        },
        "mapping_context": {
          "use_case": "clinical",
          "geographic_scope": ["International"],
          "mapping_notes": "WHO ICD-10 standard mapping for international use",
          "cross_walk_source": "WHO ICD-10 Reference"
        },
        "valid_start_date": "1990-01-01",
        "valid_end_date": "2099-12-31"
      },
      {
        "mapping_id": "map_201826_25001",
        "mapping_type": "Maps to",
        "direction": "outgoing",
        "target_concept": {
          "concept_id": 25001,
          "concept_name": "Type II diabetes mellitus",
          "concept_code": "250.00",
          "vocabulary_id": "ICD9CM",
          "vocabulary_name": "International Classification of Diseases, Ninth Revision, Clinical Modification",
          "domain_id": "Condition",
          "concept_class_id": "4-dig billing code",
          "standard_concept": "S",
          "valid_start_date": "1970-01-01",
          "valid_end_date": "2014-09-30"
        },
        "mapping_quality": {
          "confidence_score": 0.91,
          "equivalence_type": "exact",
          "semantic_similarity": 0.89,
          "mapping_source": "official",
          "validation_status": "validated",
          "last_reviewed_date": "2014-09-30"
        },
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2014-09-30"
      }
    ],
    "mapping_summary": {
      "total_mappings": 12,
      "outgoing_mappings": 8,
      "incoming_mappings": 4,
      "target_vocabularies": [
        {
          "vocabulary_id": "ICD10CM",
          "vocabulary_name": "International Classification of Diseases, Tenth Revision, Clinical Modification",
          "mapping_count": 3
        },
        {
          "vocabulary_id": "ICD10",
          "vocabulary_name": "International Classification of Diseases, Tenth Revision",
          "mapping_count": 2
        },
        {
          "vocabulary_id": "ICD9CM",
          "vocabulary_name": "International Classification of Diseases, Ninth Revision, Clinical Modification",
          "mapping_count": 7
        }
      ],
      "mapping_type_distribution": {
        "Maps to": 8,
        "Mapped from": 4
      },
      "quality_distribution": {
        "exact": 7,
        "broader": 3,
        "narrower": 1,
        "related": 1
      },
      "coverage_analysis": {
        "well_mapped_vocabularies": ["ICD10CM", "ICD10", "ICD9CM"],
        "poorly_mapped_vocabularies": [],
        "unmapped_domains": []
      }
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 12,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    },
    "query_time_ms": 87.3,
    "request_id": "req_mappings_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}
This endpoint provides comprehensive mapping information for a concept, showing how it relates to concepts in other vocabularies. These mappings are essential for data interoperability, allowing translation between different medical coding systems like SNOMED CT, ICD-10-CM, and others.

Path Parameters

concept_id
integer
required
The unique identifier of the concept to retrieve mappings for
Example: 201826 (Type 2 diabetes mellitus in SNOMED)

Query Parameters

target_vocabularies
string
Filter mappings to specific target vocabularies
Example: ICD10CM,ICD10,HCPCS
mapping_types
string
Filter by specific mapping relationship types
Default: Maps to,Mapped from
Example: Maps to,Maps to value
direction
string
default:"both"
Direction of mappings to retrieve
Options: outgoing, incoming, both
include_indirect
boolean
default:"false"
Include indirect mappings (concept → intermediate → target)
standard_only
boolean
default:"true"
Only return mappings to standard concepts
include_mapping_quality
boolean
default:"false"
Include mapping quality scores and confidence ratings
include_synonyms
boolean
default:"false"
Include synonym information for mapped concepts
include_context
boolean
default:"false"
Include contextual information about mapping relationships
active_only
boolean
default:"true"
Only include mappings to active concepts
sort_by
string
default:"vocabulary_id"
Sort mappings by specified field
Options: vocabulary_id, concept_name, mapping_quality
sort_order
string
default:"asc"
Sort order for mappings
Options: asc, desc
page_size
integer
default:"100"
Number of mappings to return per page (max 500)
page
integer
default:"1"
Page number for pagination (1-based)

Response

source_concept
object
Information about the source concept for which mappings were retrieved
mappings
array
Array of mapping relationships to other vocabularies
mapping_summary
object
Summary statistics about the mappings
meta
object
Response metadata and pagination information
curl -X GET "https://api.omophub.com/v1/concepts/201826/mappings?target_vocabularies=ICD10CM,ICD10&include_mapping_quality=true&include_synonyms=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "success": true,
  "data": {
    "source_concept": {
      "concept_id": 201826,
      "concept_name": "Type 2 diabetes mellitus",
      "concept_code": "44054006",
      "vocabulary_id": "SNOMED",
      "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    },
    "mappings": [
      {
        "mapping_id": "map_201826_45757292",
        "mapping_type": "Maps to",
        "direction": "outgoing",
        "target_concept": {
          "concept_id": 45757292,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "E11",
          "vocabulary_id": "ICD10CM",
          "vocabulary_name": "International Classification of Diseases, Tenth Revision, Clinical Modification",
          "domain_id": "Condition",
          "concept_class_id": "3-char billing code",
          "standard_concept": "S",
          "synonyms": [
            {
              "concept_synonym_name": "Type II diabetes mellitus",
              "language_concept_id": 4180186,
              "language_concept_name": "English"
            },
            {
              "concept_synonym_name": "Adult-onset diabetes",
              "language_concept_id": 4180186,
              "language_concept_name": "English"
            }
          ],
          "valid_start_date": "2016-10-01",
          "valid_end_date": "2099-12-31"
        },
        "mapping_quality": {
          "confidence_score": 0.98,
          "equivalence_type": "exact",
          "semantic_similarity": 0.95,
          "mapping_source": "official",
          "validation_status": "validated",
          "last_reviewed_date": "2024-01-15"
        },
        "mapping_context": {
          "use_case": "billing",
          "geographic_scope": ["US"],
          "temporal_scope": {
            "start_date": "2016-10-01",
            "end_date": null
          },
          "mapping_notes": "Official crosswalk mapping for ICD-10-CM billing purposes",
          "cross_walk_source": "CMS ICD-10-CM Official Guidelines"
        },
        "valid_start_date": "2016-10-01",
        "valid_end_date": "2099-12-31"
      },
      {
        "mapping_id": "map_201826_4087682",
        "mapping_type": "Maps to",
        "direction": "outgoing",
        "target_concept": {
          "concept_id": 4087682,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "E11.9",
          "vocabulary_id": "ICD10",
          "vocabulary_name": "International Classification of Diseases, Tenth Revision",
          "domain_id": "Condition",
          "concept_class_id": "ICD10 code",
          "standard_concept": "S",
          "valid_start_date": "1990-01-01",
          "valid_end_date": "2099-12-31"
        },
        "mapping_quality": {
          "confidence_score": 0.94,
          "equivalence_type": "exact",
          "semantic_similarity": 0.92,
          "mapping_source": "official",
          "validation_status": "validated",
          "last_reviewed_date": "2023-08-20"
        },
        "mapping_context": {
          "use_case": "clinical",
          "geographic_scope": ["International"],
          "mapping_notes": "WHO ICD-10 standard mapping for international use",
          "cross_walk_source": "WHO ICD-10 Reference"
        },
        "valid_start_date": "1990-01-01",
        "valid_end_date": "2099-12-31"
      },
      {
        "mapping_id": "map_201826_25001",
        "mapping_type": "Maps to",
        "direction": "outgoing",
        "target_concept": {
          "concept_id": 25001,
          "concept_name": "Type II diabetes mellitus",
          "concept_code": "250.00",
          "vocabulary_id": "ICD9CM",
          "vocabulary_name": "International Classification of Diseases, Ninth Revision, Clinical Modification",
          "domain_id": "Condition",
          "concept_class_id": "4-dig billing code",
          "standard_concept": "S",
          "valid_start_date": "1970-01-01",
          "valid_end_date": "2014-09-30"
        },
        "mapping_quality": {
          "confidence_score": 0.91,
          "equivalence_type": "exact",
          "semantic_similarity": 0.89,
          "mapping_source": "official",
          "validation_status": "validated",
          "last_reviewed_date": "2014-09-30"
        },
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2014-09-30"
      }
    ],
    "mapping_summary": {
      "total_mappings": 12,
      "outgoing_mappings": 8,
      "incoming_mappings": 4,
      "target_vocabularies": [
        {
          "vocabulary_id": "ICD10CM",
          "vocabulary_name": "International Classification of Diseases, Tenth Revision, Clinical Modification",
          "mapping_count": 3
        },
        {
          "vocabulary_id": "ICD10",
          "vocabulary_name": "International Classification of Diseases, Tenth Revision",
          "mapping_count": 2
        },
        {
          "vocabulary_id": "ICD9CM",
          "vocabulary_name": "International Classification of Diseases, Ninth Revision, Clinical Modification",
          "mapping_count": 7
        }
      ],
      "mapping_type_distribution": {
        "Maps to": 8,
        "Mapped from": 4
      },
      "quality_distribution": {
        "exact": 7,
        "broader": 3,
        "narrower": 1,
        "related": 1
      },
      "coverage_analysis": {
        "well_mapped_vocabularies": ["ICD10CM", "ICD10", "ICD9CM"],
        "poorly_mapped_vocabularies": [],
        "unmapped_domains": []
      }
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 12,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    },
    "query_time_ms": 87.3,
    "request_id": "req_mappings_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

Usage Examples

Basic Concept Mappings

Get all mappings for a concept:
const mappings = await fetch('/v1/concepts/201826/mappings');

ICD-10 Mappings Only

Get mappings to specific vocabularies:
const icdMappings = await fetch('/v1/concepts/201826/mappings?target_vocabularies=ICD10CM,ICD10');

High-Quality Mappings

Get mappings with quality information:
const qualityMappings = await fetch('/v1/concepts/201826/mappings?include_mapping_quality=true&sort_by=mapping_quality&sort_order=desc');

Outgoing Mappings Only

Get only outgoing mappings from the concept:
const outgoingMappings = await fetch('/v1/concepts/201826/mappings?direction=outgoing');

Comprehensive Mapping Analysis

Get detailed mapping information with context:
const detailedMappings = await fetch('/v1/concepts/201826/mappings?include_mapping_quality=true&include_context=true&include_synonyms=true&include_indirect=true');

Notes

  • Mappings enable interoperability between different medical coding systems
  • “Maps to” relationships typically go from non-standard to standard concepts
  • Quality scores help identify the most reliable mappings for clinical use
  • Some mappings may be contextual (e.g., billing vs. clinical use)
  • Indirect mappings provide pathways through intermediate vocabularies
  • Geographic scope indicates where mappings are officially recognized
  • Validation status shows the review and approval status of mappings
  • Standard concepts are preferred targets for most mapping applications
I