Skip to main content

​
Overview

The Recommended Concepts endpoint implements the OHDSI Phoebe algorithm to provide curated concept recommendations. This feature helps researchers discover related concepts during cohort building and phenotype development. Key Features:
  • Curated recommendations from OHDSI community data
  • Relationship-based concept discovery
  • Support for multiple source concepts
  • Filtering by vocabulary, domain, and relationship type
Use Cases:
  • Cohort building assistance
  • Phenotype expansion
  • Related concept discovery
  • Clinical terminology exploration

​
Request Body

​
concept_ids
array
required
Array of source concept IDs to get recommendations for (min: 1, max: 100)
​
relationship_types
array
Filter recommendations by relationship types (max: 20). Examples: “Has finding”, “Associated finding”, “Has clinical course”
​
vocabulary_ids
array
Filter recommended concepts to specific vocabularies (max: 50). Examples: [“SNOMED”, “ICD10CM”, “LOINC”]
​
domain_ids
array
Filter recommended concepts to specific domains (max: 50). Examples: [“Condition”, “Procedure”, “Drug”]
​
standard_only
boolean
default:"true"
Only return standard concepts (S flag in OMOP CDM)
​
include_invalid
boolean
default:"false"
Include invalid/deprecated concepts in results
​
page
number
default:"1"
Page number for pagination (min: 1)
​
page_size
number
default:"100"
Number of recommendations to return per page (min: 1, max: 1000)
curl -X POST "https://api.omophub.com/v1/concepts/recommended" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "concept_ids": [201826, 4329847],
    "standard_only": true,
    "page": 1,
    "page_size": 20
  }'

{
  "success": true,
  "data": {
    "201826": [
      {
        "concept_id": 4193704,
        "concept_name": "Hyperglycemia",
        "vocabulary_id": "SNOMED",
        "concept_code": "80394007",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "invalid_reason": null,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "relationship_id": "Has finding"
      },
      {
        "concept_id": 4058243,
        "concept_name": "Diabetic retinopathy",
        "vocabulary_id": "SNOMED",
        "concept_code": "4855003",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "invalid_reason": null,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "relationship_id": "Associated finding"
      },
      {
        "concept_id": 3004410,
        "concept_name": "Hemoglobin A1c measurement",
        "vocabulary_id": "LOINC",
        "concept_code": "4548-4",
        "domain_id": "Measurement",
        "concept_class_id": "Lab Test",
        "standard_concept": "S",
        "invalid_reason": null,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "relationship_id": "Has finding"
      }
    ],
    "4329847": [
      {
        "concept_id": 437894,
        "concept_name": "Coronary arteriosclerosis",
        "vocabulary_id": "SNOMED",
        "concept_code": "53741008",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "invalid_reason": null,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "relationship_id": "Associated finding"
      },
      {
        "concept_id": 4213540,
        "concept_name": "Troponin measurement",
        "vocabulary_id": "LOINC",
        "concept_code": "6598-7",
        "domain_id": "Measurement",
        "concept_class_id": "Lab Test",
        "standard_concept": "S",
        "invalid_reason": null,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "relationship_id": "Has finding"
      }
    ]
  },
  "meta": {
    "request_id": "rec_1234567890_abc",
    "vocab_release": "2025.2",
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 296,
      "total_pages": 3,
      "has_next": true,
      "has_previous": false
    }
  }
}

​
Implementation Notes

​
Data Source

  • Data is curated by the OHDSI community using the Phoebe algorithm
  • Version-independent: recommendations persist across vocabulary releases

​
Response Structure

  • Results are grouped by source concept ID
  • Each source concept ID maps to an array of recommended concepts
  • Recommendations include full concept details and relationship information

​
Filtering

  • Apply multiple filters simultaneously (vocabulary, domain, relationship type)
  • standard_only=true (default) filters to standard concepts only
  • include_invalid=false (default) excludes deprecated concepts