Skip to main content

​
Get a Concept

Retrieve a concept by its OMOP concept ID: 
concept <- client$concepts$get(201826)
print(concept$concept_name)   # "Type 2 diabetes mellitus"
print(concept$vocabulary_id)  # "SNOMED"
print(concept$domain_id)      # "Condition"

​
Get by Vocabulary Code

Look up a concept using a vocabulary-specific code: 
# Get SNOMED concept by its code
concept <- client$concepts$get_by_code("SNOMED", "44054006")
print(concept$concept_name)  # "Type 2 diabetes mellitus"

# Get ICD-10-CM concept
concept <- client$concepts$get_by_code("ICD10CM", "E11")

# Include synonyms and relationships
concept <- client$concepts$get_by_code(
  "SNOMED",
  "44054006",
  include_synonyms = TRUE,
  include_relationships = TRUE
)
print(concept$synonyms)       # List of synonym names
print(concept$relationships)  # list(parents = [...], children = [...])

# Specify vocabulary release version
concept <- client$concepts$get_by_code(
  "SNOMED",
  "44054006",
  vocab_release = "2025.2"
)

​
Batch Get Concepts

Retrieve multiple concepts in a single request (max 100): 
# Basic batch request
result <- client$concepts$batch(c(201826, 4329847, 1112807))
for (concept in result$data$concepts) {
  cat(sprintf("%s: %s\n", concept$concept_id, concept$concept_name))
}

# With optional parameters
result <- client$concepts$batch(
  c(201826, 4329847, 1112807),
  include_relationships = TRUE,
  include_synonyms = TRUE,
  include_mappings = TRUE,
  vocabulary_filter = c("SNOMED"),
  standard_only = FALSE  # default
)

# Check summary
cat(sprintf("Retrieved: %d\n", result$data$summary$successful_retrievals))
cat(sprintf("Failed: %d\n", result$data$summary$failed_retrievals))

​
Autocomplete Suggestions

Get concept suggestions for autocomplete functionality: 
# Basic suggestions with pagination
result <- client$concepts$suggest("diab", page_size = 10)
for (concept in result$data) {
  print(concept$concept_name)
}

# Check pagination metadata
print(result$meta$pagination$total_items)
print(result$meta$pagination$has_next)

# Filter by vocabulary and domain
result <- client$concepts$suggest(
  "diab",
  vocabulary_ids = c("SNOMED"),
  domain_ids = c("Condition"),
  page_size = 20
)

# Navigate pages
result <- client$concepts$suggest("diab", page = 2, page_size = 10)

​
Get Relationships

Get relationships for a concept: 
# Get all relationships with pagination
result <- client$relationships$get(201826)
for (rel in result$data$relationships) {
  cat(sprintf("%s: %s\n", rel$relationship_id, rel$concept_2$concept_name))
}

# Check pagination
cat(sprintf("Page %d of %d\n",
  result$meta$pagination$page,
  result$meta$pagination$total_pages
))
cat(sprintf("Total relationships: %d\n", result$meta$pagination$total_items))

# Filter by relationship type and vocabulary
result <- client$relationships$get(
  201826,
  relationship_ids = c("Is a", "Subsumes"),
  vocabulary_ids = "SNOMED",
  standard_only = TRUE,
  page = 1,
  page_size = 50
)

# Include reverse relationships
result <- client$relationships$get(
  201826,
  include_reverse = TRUE,
  domain_ids = c("Condition")
)

​
Get Complete Hierarchy

Get both ancestors and descendants in a single request: 
# Flat format (default) - separate arrays for ancestors and descendants
result <- client$hierarchy$get(
  201826,
  max_levels = 3,
  vocabulary_ids = c("SNOMED")
)

cat(sprintf("Total ancestors: %d\n", result$data$total_ancestors))
cat(sprintf("Total descendants: %d\n", result$data$total_descendants))

# Graph format for visualization (D3.js, Cytoscape, etc.)
graph <- client$hierarchy$get(
  201826,
  format = "graph",
  max_levels = 3
)

nodes <- graph$data$nodes  # Concept nodes
edges <- graph$data$edges  # Relationship edges
cat(sprintf("Nodes: %d, Edges: %d\n", length(nodes), length(edges)))

# Advanced filtering options
result <- client$hierarchy$get(
  201826,
  domain_ids = c("Condition"),
  relationship_types = c("Is a"),
  max_results = 100,
  include_invalid = FALSE
)

​
Hierarchy Get Parameters

ParameterTypeDefaultDescription
concept_idintegerrequiredThe concept ID
formatcharacter”flat”Response format (“flat” or “graph”)
vocabulary_idscharacterNULLFilter to specific vocabularies
domain_idscharacterNULLFilter to specific domains
max_levelsinteger10Maximum hierarchy levels (max 20)
max_resultsintegerNULLMaximum results per direction
relationship_typescharacterNULLRelationship types to follow
include_invalidlogicalTRUEInclude deprecated/invalid concepts

​
Get Ancestors

Find parent concepts in the hierarchy: 
result <- client$hierarchy$ancestors(
  201826,
  max_levels = 3,
  vocabulary_ids = c("SNOMED"),     # Filter to specific vocabularies
  relationship_types = c("Is a"),   # Relationship types to follow
  include_distance = TRUE,          # Include hierarchy_level field
  include_paths = FALSE,            # Include path information
  include_invalid = FALSE,          # Exclude deprecated concepts
  page = 1,
  page_size = 100
)

# Access source concept info
cat(sprintf("Ancestors of: %s\n", result$concept_name))

# Access ancestors
for (ancestor in result$ancestors) {
  level <- ancestor$hierarchy_level %||% 0
  cat(sprintf("%s%s\n", strrep("  ", level), ancestor$concept_name))
}

# Access hierarchy summary
cat(sprintf("Max depth: %d\n", result$hierarchy_summary$max_hierarchy_depth))

# Access pagination
cat(sprintf("Page %d of %d\n",
  result$meta$pagination$page,
  result$meta$pagination$total_pages
))

​
Ancestors Parameters

ParameterTypeDefaultDescription
concept_idintegerrequiredThe concept ID
vocabulary_idscharacterNULLFilter to specific vocabularies
max_levelsintegerNULLMaximum hierarchy levels to traverse
relationship_typescharacterNULLRelationship types to follow (default: “Is a”)
include_pathslogicalFALSEInclude path information
include_distancelogicalTRUEInclude hierarchy_level field
include_invalidlogicalTRUEInclude deprecated/invalid concepts
pageinteger1Page number
page_sizeinteger100Results per page

​
Get Descendants

Find child concepts in the hierarchy: 
result <- client$hierarchy$descendants(
  201826,
  max_levels = 2,
  vocabulary_ids = c("SNOMED"),     # Filter to specific vocabularies
  relationship_types = c("Is a"),   # Relationship types to follow
  include_distance = TRUE,          # Include hierarchy_level field
  include_paths = FALSE,            # Include path information
  include_invalid = FALSE,          # Exclude deprecated concepts
  domain_ids = c("Condition"),      # Filter by domain
  page = 1,
  page_size = 100
)

# Access descendants
for (descendant in result$descendants) {
  print(descendant$concept_name)
}

# Access pagination
cat(sprintf("Page %d of %d\n",
  result$meta$pagination$page,
  result$meta$pagination$total_pages
))

​
Descendants Parameters

ParameterTypeDefaultDescription
concept_idintegerrequiredThe concept ID
vocabulary_idscharacterNULLFilter to specific vocabularies
max_levelsinteger10Maximum hierarchy levels (max 20)
relationship_typescharacterNULLRelationship types to follow (default: “Is a”)
include_distancelogicalTRUEInclude hierarchy_level field
include_pathslogicalFALSEInclude path information
include_invalidlogicalTRUEInclude deprecated/invalid concepts
domain_idscharacterNULLFilter by domains
pageinteger1Page number
page_sizeinteger100Results per page

​
Get Relationship Types

Get available relationship types from the OMOP CDM: 
# Get relationship types with pagination
result <- client$relationships$types(page = 1, page_size = 100)

for (rel_type in result$data) {
  cat(sprintf("%s: %s\n", rel_type$relationship_id, rel_type$relationship_name))
}

# Access pagination
cat(sprintf("Total types: %d\n", result$meta$pagination$total_items))

​
With Options

Include synonyms, relationships, hierarchy, and specify vocabulary release: 
# Get concept with synonyms
concept <- client$concepts$get(
  201826,
  include_synonyms = TRUE
)

# Get concept with synonyms and relationships
concept <- client$concepts$get(
  201826,
  include_synonyms = TRUE,
  include_relationships = TRUE
)
print(concept$relationships)  # list(parents = [...], children = [...])

# Get concept with hierarchy information
concept <- client$concepts$get(
  201826,
  include_hierarchy = TRUE
)
print(concept$hierarchy)  # Ancestor/descendant summary

# Specify vocabulary release version
concept <- client$concepts$get(
  201826,
  vocab_release = "2025.2"
)

​
Parameters

ParameterTypeDefaultDescription
concept_idintegerrequiredThe OMOP concept ID
include_relationshipslogicalFALSEInclude related concepts (parents/children)
include_synonymslogicalFALSEInclude concept synonyms
include_hierarchylogicalFALSEInclude hierarchy information
vocab_releasecharacterNULLSpecific vocabulary release (e.g., “2025.2”)

​
Get Concept Relationships

Get detailed relationships for a concept with filtering options: 
# Get all relationships
result <- client$concepts$relationships(201826)
for (rel in result$data$relationships) {
  cat(sprintf("%s: %s\n", rel$relationship_id, rel$concept_2$concept_name))
}

# Filter by relationship type and vocabulary
result <- client$concepts$relationships(
  201826,
  relationship_ids = c("Is a", "Subsumes"),
  vocabulary_ids = "SNOMED",
  standard_only = TRUE
)

# Include reverse relationships
result <- client$concepts$relationships(
  201826,
  include_reverse = TRUE,
  domain_ids = c("Condition")
)

​
Relationships Parameters

ParameterTypeDefaultDescription
concept_idintegerrequiredThe concept ID
relationship_idscharacterNULLFilter by relationship type IDs
vocabulary_idscharacterNULLFilter by target vocabulary IDs
domain_idscharacterNULLFilter by target domain IDs
include_invalidlogicalTRUEInclude relationships to invalid concepts
standard_onlylogicalFALSEOnly include relationships to standard concepts
include_reverselogicalFALSEInclude reverse relationships
vocab_releasecharacterNULLSpecific vocabulary release version
Find concepts related to a given concept: 
# Basic related concepts
result <- client$concepts$related(201826, page_size = 10)
for (related in result$data) {
  cat(sprintf("%s (%s): score %.2f\n",
    related$concept_name,
    related$relationship_id,
    related$relationship_score
  ))
}

# Filter by relationship type and minimum score
result <- client$concepts$related(
  201826,
  relationship_types = c("Is a", "Maps to"),
  min_score = 0.5,
  page_size = 20
)

# Specify vocabulary release
result <- client$concepts$related(
  201826,
  vocab_release = "2025.1"
)
Get curated concept recommendations using the OHDSI Phoebe algorithm: 
# Basic recommendations for diabetes-related concepts
result <- client$concepts$recommended(c(201826, 4329847))
for (source_id in names(result$data)) {
  cat(sprintf("\nRecommendations for concept %s:\n", source_id))
  for (rec in head(result$data[[source_id]], 5)) {
    cat(sprintf("  - %s (%s) via %s\n",
      rec$concept_name,
      rec$vocabulary_id,
      rec$relationship_id
    ))
  }
}

# With filters
result <- client$concepts$recommended(
  c(201826),
  relationship_types = c("Has finding", "Associated finding"),
  vocabulary_ids = c("SNOMED", "LOINC"),
  domain_ids = c("Condition", "Measurement"),
  standard_only = TRUE,
  page_size = 50
)

# Access pagination metadata
cat(sprintf("Page %d of %d\n",
  result$meta$pagination$page,
  result$meta$pagination$total_pages
))
cat(sprintf("Total recommendations: %d\n", result$meta$pagination$total_items))