> ## 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 Similar Concepts by ID

> Find OMOP concepts similar to a specific concept identified by its concept ID using semantic similarity - discover related clinical terminology fast.

## Overview

This endpoint finds medical concepts that are semantically similar to a specific concept identified by its OMOP concept ID. It uses the same advanced machine learning algorithms as the POST version but optimized for concept-to-concept similarity matching, making it ideal for discovering related concepts when you have a specific starting point.

## Path Parameters

<ParamField path="conceptId" type="integer" required>
  The OMOP concept ID to find similar concepts for
</ParamField>

## Query Parameters

<ParamField query="vocabulary_ids" type="string">
  Target vocabularies to search within (comma-separated)

  <br />

  **Examples**: `SNOMED`, `SNOMED,ICD10CM`, `RXNORM,NDC`
</ParamField>

<ParamField query="domain_ids" type="string">
  Clinical domains to focus the similarity search (comma-separated)

  <br />

  **Examples**: `Condition,Procedure`, `Drug,Device`
</ParamField>

<ParamField query="concept_class_ids" type="string">
  Concept classes to include in similarity search (comma-separated)

  <br />

  **Examples**: `Clinical Finding,Procedure`, `Ingredient,Brand Name`
</ParamField>

<ParamField query="similarity_threshold" type="number" default="0.7" min="0.0" max="1.0">
  Minimum similarity score threshold (0.0 to 1.0)

  <br />

  **Higher values** = More strict similarity matching
</ParamField>

<ParamField query="page_size" type="integer" default="20" min="1" max="100">
  Number of similar concepts to return per page
</ParamField>

<ParamField query="page" type="integer" default="1" min="1">
  Page number (1-based indexing)
</ParamField>

<ParamField query="include_scores" type="boolean" default="true">
  Include similarity scores in the response
</ParamField>

<ParamField query="include_explanations" type="boolean" default="false">
  Include explanations for why concepts are considered similar
</ParamField>

<ParamField query="standard_concept" type="string">
  Filter to standard concepts only

  <br />

  **Options**: `S` (standard), `C` (classification), `NULL` (non-standard)
</ParamField>

<ParamField query="include_invalid" type="boolean" default="true">
  Include invalid/deprecated concepts in similarity search
</ParamField>

<ParamField query="algorithm" type="string" default="hybrid">
  Similarity algorithm to use

  <br />

  **Options**: `semantic` (embedding-based), `lexical` (text-based), `hybrid` (combined)
</ParamField>

<ParamField query="exclude_self" type="boolean" default="true">
  Exclude the source concept from results
</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
    </ResponseField>

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

    <ResponseField name="details" type="object">
      Additional error details or context
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="object">
  Contains the similar concepts search results

  <Expandable title="data">
    <ResponseField name="source_concept" type="object">
      Information about the source concept used for similarity search

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

        <ResponseField name="concept_name" type="string">
          Primary name of the source concept
        </ResponseField>

        <ResponseField name="concept_code" type="string">
          Vocabulary-specific code
        </ResponseField>

        <ResponseField name="vocabulary_id" type="string">
          Source vocabulary identifier
        </ResponseField>

        <ResponseField name="domain_id" type="string">
          Clinical domain classification
        </ResponseField>

        <ResponseField name="concept_class_id" type="string">
          Concept class identifier
        </ResponseField>

        <ResponseField name="standard_concept" type="string|null">
          Standard concept designation ('S', 'C', or null for non-standard)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="similar_concepts" type="array">
      Array of concepts similar to the source concept

      <Expandable title="similar_concepts">
        <ResponseField name="concept_id" type="integer">
          OMOP concept ID
        </ResponseField>

        <ResponseField name="concept_name" type="string">
          Primary concept name
        </ResponseField>

        <ResponseField name="concept_code" type="string">
          Vocabulary-specific concept code
        </ResponseField>

        <ResponseField name="vocabulary_id" type="string">
          Source vocabulary identifier
        </ResponseField>

        <ResponseField name="domain_id" type="string">
          Clinical domain classification
        </ResponseField>

        <ResponseField name="concept_class_id" type="string">
          Concept class identifier
        </ResponseField>

        <ResponseField name="similarity_score" type="number">
          Similarity score between 0.0 and 1.0
        </ResponseField>

        <ResponseField name="explanation" type="string">
          Reason for similarity match (if requested)
        </ResponseField>

        <ResponseField name="standard_concept" type="string|null">
          Standard concept designation ('S', 'C', or null for non-standard)
        </ResponseField>

        <ResponseField name="synonyms" type="array">
          Alternative names for the concept
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="search_metadata" type="object">
      Information about the similarity search

      <Expandable title="search_metadata">
        <ResponseField name="source_concept_id" type="integer">
          The concept ID used as the similarity source
        </ResponseField>

        <ResponseField name="algorithm_used" type="string">
          Similarity algorithm applied
        </ResponseField>

        <ResponseField name="similarity_threshold" type="number">
          Minimum similarity threshold applied
        </ResponseField>

        <ResponseField name="total_candidates" type="integer">
          Total concepts evaluated for similarity
        </ResponseField>

        <ResponseField name="results_returned" type="integer">
          Number of similar concepts returned
        </ResponseField>

        <ResponseField name="processing_time_ms" type="integer">
          Search processing time in milliseconds
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.omophub.com/v1/search/similar/44054006?vocabulary_ids=SNOMED,ICD10CM&similarity_threshold=0.8&page_size=10&include_scores=true&include_explanations=true" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.omophub.com/v1/search/similar/44054006?vocabulary_ids=SNOMED,ICD10CM&similarity_threshold=0.8&page_size=10&include_scores=true&include_explanations=true',
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );
  const data = await response.json();
  ```

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

  url = "https://api.omophub.com/v1/search/similar/44054006"
  params = {
      "vocabulary_ids": "SNOMED,ICD10CM",
      "similarity_threshold": 0.8,
      "page_size": 10,
      "include_scores": "true",
      "include_explanations": "true"
  }

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

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "source_concept": {
        "concept_id": 44054006,
        "concept_name": "Type 2 diabetes mellitus",
        "concept_code": "44054006",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S"
      },
      "similar_concepts": [
        {
          "concept_id": 201826,
          "concept_name": "Type 2 diabetes mellitus without complications",
          "concept_code": "E11.9",
          "vocabulary_id": "ICD10CM",
          "domain_id": "Condition",
          "concept_class_id": "4-char nonbill code",
          "similarity_score": 0.92,
          "explanation": "High similarity - more specific variant of the same condition",
          "standard_concept": null,
          "synonyms": ["Type II diabetes mellitus uncomplicated"]
        },
        {
          "concept_id": 443729,
          "concept_name": "Diabetes mellitus type 2 with hyperglycemia",
          "concept_code": "443729",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "similarity_score": 0.89,
          "explanation": "High similarity - related complication of the same condition",
          "standard_concept": "S",
          "synonyms": ["Type 2 DM with elevated glucose"]
        },
        {
          "concept_id": 432367,
          "concept_name": "Diabetes mellitus type 2 with diabetic nephropathy",
          "concept_code": "E11.21",
          "vocabulary_id": "ICD10CM",
          "domain_id": "Condition",
          "concept_class_id": "5-char billing code",
          "similarity_score": 0.86,
          "explanation": "High similarity - complication of the same condition",
          "standard_concept": null,
          "synonyms": ["Type 2 DM with kidney disease"]
        }
      ],
      "search_metadata": {
        "source_concept_id": 44054006,
        "algorithm_used": "hybrid",
        "similarity_threshold": 0.8,
        "total_candidates": 125000,
        "results_returned": 3,
        "processing_time_ms": 187
      }
    },
    "meta": {
      "request_id": "req_sim_xyz789",
      "timestamp": "2024-01-15T10:30:00Z",
      "vocab_release": "2025.1",
      "pagination": {
        "page": 1,
        "page_size": 20,
        "total_items": 3,
        "total_pages": 1,
        "has_next": false,
        "has_previous": false
      },
      "search": {
        "query": "",
        "total_results": 3,
        "filters_applied": {
          "similarity_type": "concept"
        }
      }
    }
  }
  ```

  ```json Error Response theme={null}
  {
    "success": false,
    "error": {
      "code": "CONCEPT_NOT_FOUND",
      "message": "The specified concept ID does not exist",
      "details": {
        "concept_id": 99999999,
        "suggestion": "Verify the concept ID exists in the OMOP vocabularies"
      }
    }
  }
  ```
</ResponseExample>

## Usage Examples

### Basic Similarity by ID

Find concepts similar to Type 2 Diabetes (concept ID 44054006):

```bash theme={null}
GET /v1/search/similar/44054006?page_size=5&similarity_threshold=0.7
```

### Cross-Vocabulary Similarity

Find similar concepts across multiple vocabularies:

```bash theme={null}
GET /v1/search/similar/1308216?vocabulary_ids=SNOMED,ICD10CM,LOINC&domain_ids=Condition,Measurement&include_explanations=true
```

### Drug Similarity Search

Find similar pharmaceutical concepts:

```bash theme={null}
GET /v1/search/similar/1503297?vocabulary_ids=RXNORM&domain_ids=Drug&concept_class_ids=Ingredient,Clinical Drug&similarity_threshold=0.8
```

### High-Precision Similarity

Get only highly similar concepts with detailed scoring:

```bash theme={null}
GET /v1/search/similar/443390?similarity_threshold=0.9&page_size=10&include_scores=true&algorithm=semantic
```

## Performance Notes

* **Concept-to-concept similarity** is typically faster than query-based similarity
* **Hybrid algorithm** provides best balance of accuracy and performance
* **Semantic algorithm** is most accurate but computationally intensive
* **Caching** is applied for frequently requested concept similarities

## Related Endpoints

* [POST Search Similar](/api-reference/search/search-similar) - Find similar concepts using query text
* [Get Concept](/api-reference/concepts/get-concept) - Get detailed information about a specific concept