We've added support for Phoebe recommended concepts, bringing powerful phenotype development capabilities to the OMOPHub API.

What is Phoebe?

Phoebe (PHenotype Observable Entity Baseline Extraction) is an OHDSI tool that provides recommended concepts for phenotype definitions. It analyzes real-world data to suggest which concepts are most commonly used together, helping researchers build more comprehensive and accurate phenotype definitions.

New Endpoint

The new POST /v1/concepts/recommended endpoint returns concepts that are frequently associated with given concepts:

POST /v1/concepts/recommended
Content-Type: application/json

{
  "concept_ids": [201826],
  "standard_only": true,
  "page_size": 20
}

This returns recommended concepts for "Type 2 diabetes mellitus" (concept ID 201826) based on Phoebe's analysis of real-world observational data. You can query multiple concepts at once by adding more IDs to the concept_ids array.

Parameters

Parameter	Type	Required	Description
`concept_ids`	array of integers	Yes	One or more concept IDs to find recommendations for
`standard_only`	boolean	No	Filter to standard concepts only (default: `false`)
`page_size`	integer	No	Number of results (1-100, default: 20)

Response Example

{
  "concepts": [
    {
      "concept_id": 443238,
      "concept_name": "Diabetic retinopathy",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "standard_concept": "S",
      "recommendation_score": 0.89
    },
    {
      "concept_id": 192279,
      "concept_name": "Diabetic nephropathy",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "standard_concept": "S",
      "recommendation_score": 0.85
    }
  ],
  "meta": {
    "source_concept_ids": [201826],
    "total_results": 2,
    "vocab_release": "2025.2"
  }
}

Error Responses

400 Bad Request: Invalid or missing concept_ids
401 Unauthorized: Missing or invalid API key
404 Not Found: No recommendations available for the given concept IDs

Use Cases

Phenotype Development

When building a phenotype definition, you can now:

Start with a seed concept (e.g., a condition)
Retrieve recommended concepts from Phoebe
Review and include relevant concepts in your definition
Build more comprehensive phenotypes with less manual effort

Check out our detailed Phenotype Development Guide for step-by-step examples.

Documentation

This feature is available to all API users with no additional configuration required.