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

integer[]
required
Array of source concept IDs to get recommendations for (min: 1, max: 100)
string[]
Filter recommendations by relationship types (max: 20). Examples: “Has finding”, “Associated finding”, “Has clinical course”
string[]
Filter recommended concepts to specific vocabularies (max: 50). Examples: [“SNOMED”, “ICD10CM”, “LOINC”]
string[]
Filter recommended concepts to specific domains (max: 50). Examples: [“Condition”, “Procedure”, “Drug”]
boolean
default:"false"
Only return standard concepts (S flag in OMOP CDM)
boolean
default:"false"
Include invalid/deprecated concepts in results
integer
default:"1"
Page number for pagination (min: 1)
integer
default:"100"
Number of recommendations to return per page (min: 1, max: 1000)

Response Fields

boolean
Whether recommendation lookup succeeded.
object
Map keyed by each requested source concept_id.
array
Recommendations for one source concept.
integer
Recommended concept identifier.
string
Recommended concept name.
string
Vocabulary identifier.
string
Vocabulary code.
string
OMOP domain.
string
Concept class.
string | null
S, C, or null.
string | null
Invalidity marker, or null.
string
Validity start date.
string
Validity end date.
string
Relationship supporting the recommendation.
object
Request, release, and pagination metadata.
string
Request correlation ID.
string
Vocabulary release used.
object
Page, page size, totals, and navigation flags.

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=false (default) includes all concepts; set to true to filter to standard concepts only
  • include_invalid=false (default) excludes deprecated concepts